General Mission Analysis Tool (GMAT)

User Guide

The GMAT Development Team


Table of Contents

Documentation Overview
Using GMAT
Tutorials
Reference Guide
Using GMAT
1. Welcome to GMAT
Features Overview
Dynamics and Environment Modelling
Plotting, Reporting and Product Generation
Optimization and Targeting
Programming Infrastructure
Interfaces
Licensing
Platform Support
Development Status and Usage
Contributors
2. Getting Started
Installation
Running GMAT
Starting GMAT
Exiting GMAT
Sample Missions
Getting Help
3. Tour of GMAT
User Interfaces Overview
GUI Overview
Script Interface Overview
GUI/Script Interface Interactions and Rules
Resources Tree
Organization
Folder Menus
Resource Menus
Mission Tree
Mission Tree Display
View Filters Toolbar
Mission Sequence Menu
Command Menu
Docking/Undocking/Placement
Command Summary
Data Availability
Data Contents
Supported Commands
Coordinate Systems
Output Tree
Script Editor
Active Script
GUI/Script Synchronization
Scripts List
Edit Window
Find and Replace
File Controls
Save Status Indicator
4. Configuring GMAT
File Structure
bin
data
docs
extras
matlab
output
plugins
samples
userfunctions
Configuring Data Files
Leap Second and EOP files
Loading Custom Plugins
Configuring the MATLAB Inteface
User-defined Function Paths
Tutorials
5. Simulating an Orbit
Objective and Overview
Configure the Spacecraft
Rename the Spacecraft
Set the Spacecraft Epoch
Set the Keplerian Orbital Elements
Configure the Propagator
Rename the Propagator
Configure the Force Model
Configuring the Orbit View Plot
Configure the Propagate Command
Run and Analyze the Results
6. Simple Orbit Transfer
Objective and Overview
Configure Maneuvers, Differential Corrector, and Graphics
Create the Differential Corrector
Modify the Default Orbit View
Create the Maneuvers.
Configure the Mission Sequence
Configure the Initial Propagate Command
Create the Target Sequence
Create the Final Propagate Command
Configure the Target Sequence
Run the Mission
7. Target Finite Burn to Raise Apogee
Objective and Overview
Create and Configure Spacecraft Hardware and Finite Burn
Create a Thruster and a Fuel Tank
Modify Thruster1 Thrust Coefficients
Attach FuelTank1 and Thruster1 to DefaultSC
Create the Finite Burn Maneuver
Create the Differential Corrector and Target Control Variable
Configure the Mission Sequence
Configure the Initial Propagate Command
Create the Target Sequence
Configure the Target Sequence
Run the Mission
Inspect Orbit View and Message Window
Explore the Command Summary Reports
8. Mars B-Plane Targeting
Objective and Overview
Configure Fuel Tank, Spacecraft properties, Maneuvers, Propagators, Differential Corrector, Coordinate Systems and Graphics
Create Fuel Tank
Modify the DefaultSC Resource
Create the Maneuvers
Create the Propagators
Create the Differential Corrector
Create the Coordinate Systems
Create the Orbit Views
Configure the Mission Sequence
Create the First Target Sequence
Configure the First Target Sequence
Configure the Target desired B-plane Coordinates Command
Configure the Prop 3 Days Command
Configure the Prop 12 Days to TCM Command
Configure the Vary TCM.V Command
Configure the Vary TCM.N Command
Configure the Vary TCM.B Command
Configure the Apply TCM Command
Configure the Prop 280 Days Command
Configure the Prop to Mars Periapsis Command
Configure the Achieve BdotT Command
Configure the Achieve BdotR Command
Run the Mission with first Target Sequence
Create the Second Target Sequence
Create the Final Propagate Command
Configure the second Target Sequence
Configure the Mars Capture Command
Configure the Vary MOI.V Command
Configure the Apply MOI Command
Configure the Prop to Mars Apoapsis Command
Configure the Achieve RMAG Command
Run the Mission with first and second Target Sequences
9. Optimal Lunar Flyby using Multiple Shooting
Objective and Overview
Configure Coordinate Systems, Spacecraft, Optimizer, Propagators, Maneuvers, Variables, and Graphics
Create a Moon-centered Coordinate System
Create the Spacecraft
Create the Propagators
Create the Maneuvers
Create the User Variables
Create the Optimizer
Create the 3-D Graphics
Create XPPlots/Reports
Configure the Mission Sequence
Overview of the Mission Sequence
Define Initial Guesses
Initialize Variables
Vary and Set Spacecraft Epochs
Vary Control Point States
Apply Constraints at Control Points
Propagate the Segments
Compute Some Quantities and Apply Patch Constraints
Apply Patch Point Constraints
Apply Constraints on Mission Orbit
Apply Cost Function
Design the Trajectory
Overview
Step 1: Verify Your Configuration
Step 2: Find a Smooth Trajectory
Step 5: Apply a New Constraint
Reference Guide
I. Resources
Array — A user-defined one- or two-dimensional array variable
Barycenter — The center of mass of selected celestial bodies
CelestialBody — A celestial body model
CoordinateSystem — An axis and origin pair
DifferentialCorrector — A numerical solver
EphemerisFile — Generate spacecraft’s ephemeris data
FiniteBurn — A finite burn
FminconOptimizer — The Sequential Quadratic Processor (SQP) optimizer, fmincon
Formation — A collection of spacecraft.
FuelTank — Model of a chemical fuel tank
GroundStation — A ground station model.
GroundTrackPlot — A user-defined resource that draws longitude and latitude time-history of a spacecraft
ImpulsiveBurn — An impulsive maneuver
LibrationPoint — An equilibrium point in the circular, restricted 3-body problem
MatlabFunction — Declaration of an external MATLAB function
OrbitView — A user-defined resource that plots 3-Dimensional trajectories
Propagator — A propagator models spacecraft motion
ReportFile — Report data to a text file
SolarSystem — High level solar system configuration options
Spacecraft — A spacecraft model
Spacecraft Attitude — The spacecraft attitude model
Spacecraft Ballistic/Mass Properties — The physical properties of the spacecraft
Spacecraft Epoch — The spacecraft epoch
Spacecraft Hardware — Add hardware to a spacecraft
Spacecraft Orbit State — The orbital initial conditions
Spacecraft Visualization Properties — The visual properties of the spacecraft
String — A user-defined string variable
Thruster — A chemical thruster model
Variable — A user-defined numeric variable
VF13ad — The Sequential Quadratic Processor (SQP) optimizer, VF13ad
XYPlot — Plots data onto the X and Y axes of a graph
II. Commands
Achieve — Specify a goal for a Target sequence
Assignment (=) — Set a variable or resource field to a value, possibly using mathematical expressions
BeginFiniteBurn — Model finite thrust maneuvers
BeginMissionSequence — Begin the mission sequence portion of a script
BeginScript — Execute free-form script commands
CallMatlabFunction — Call a MATLAB function
ClearPlot — Allows you to clear all data from an XYPlot
EndFiniteBurn — Model finite thrust maneuvers in the mission sequence
Equation — Perform an equation command
For — Execute a series of commands a specified number of times
If — Conditionally execute a series of commands
Maneuver — Perform an impulsive (instantaneous) maneuver
MarkPoint — Allows you to add a special mark point character on an XYPlot
Minimize — Define the cost function to minimize
NonlinearConstraint — Specify a constraint used during optimization
Optimize — Solve for condition(s) by varying one or more parameters
PenUpPenDown — Allows you to stop or begin drawing data on a plot
Propagate — Propagates spacecraft to a requested stopping condition
Report — Allows you to write data to a text file
Stop — Stop mission execution
Target — Solve for condition(s) by varying one or more parameters
Toggle — Allows you to turn data output off or on
Vary — Specifies variables used by a solver
While — Execute a series of commands repeatedly while a condition is met
III. System
Calculation Parameters — Resource properties available for use by commands and output
Command-Line Usage — Starting the GMAT application from the command line
MATLAB Interface — Interface to MATLAB system
Script Language — The GMAT script language
Startup File — The gmat_startup_file.txt configuration file
Release Notes
GMAT R2013a Release Notes
Licensing
Major Improvements
Minor Enhancements
Compatibility Changes
Known & Fixed Issues
GMAT R2012a Release Notes
New Features
Improvements
Compatibility Changes
Known & Fixed Issues
GMAT R2011a Release Notes
New Features
Improvements
Compatibility Changes
Fixed Issues
Known Issues
Index

List of Figures

3.1. GMAT Desktop (Windows)
3.2. Undocked Mission Tree
3.3. GMAT Script Editor
3.4. Default Resources tree
3.5. Folder menu for Spacecraft
3.6. Folder menu for Hardware
3.7. Resource menu
3.8. Parts of the script editor
3.9. Active script indicators
4.1. GMAT Root Directory Structure
4.2. GMAT Data Directory Structure
5.1. Spacecraft State Setup
5.2. Force Model Configuration
5.3. DefaultOrbitView Configuration
5.4. Propagate Command ParameterSelectDialog Configuration
5.5. Propagate Command Configuration
5.6. Orbit View Plot after Mission Run
6.1. Final Mission Sequence for the Hohmann Transfer
6.2. Prop One Day Command Configuration
6.3. Vary TOI Command Configuration
6.4. Perform TOI Command Configuration
6.5. Prop to Apoapsis Command Configuration
6.6. Achieve RMAG = 42165 Command Configuration
6.7. Vary GOI Parameter Selection
6.8. Vary GOI Command Configuration
6.9. Perform GOI Command Configuration
6.10. Achieve ECC = 0.005 Command Configuration
6.11. 3D View of Hohmann Transfer
7.1. FuelTank1 Configuration
7.2. Thruster1 Configuration
7.3. Thruster1 Thrust Coefficients
7.4. Attach FuelTank1 to DefaultSC
7.5. Attach Thruster1 to DefaultSC
7.6. Creation of FiniteBurn Resource FiniteBurn1
7.7. Creation of Variable Resource, BurnDuration
7.8. Prop To Perigee Command Configuration
7.9. Final Mission Sequence
7.10. Raise Apogee Command Configuration
7.11. Vary Burn Duration Command Configuration
7.12. Turn Thruster On Command Configuration
7.13. Prop BurnDuration Command Configuration
7.14. Turn Thruster Off Command Configuration
7.15. Prop To Apogee Command Configuration
7.16. Achieve Apogee Radius = 12000 Command Configuration
7.17. 3D View of Finite Burn to Raise Apogee
8.1. Geometry of the B-Plane as seen from a viewpoint perpendicular to the B-Plane
8.2. The B-vector as seen from a viewpoint perpendicular to orbit plane
8.3. Mission Sequence for the First Target sequence
8.4. Target desired B-plane Coordinates Command Configuration
8.5. Prop 3 Days Command Configuration
8.6. Prop 12 Days to TCM Command Configuration
8.7. Vary TCM.V Command Configuration
8.8. Vary TCM.N Parameter Selection
8.9. Vary TCM.N Command Configuration
8.10. Vary TCM.B Parameter Selection
8.11. Vary TCM.N Command Configuration
8.12. Apply TCM Command Configuration
8.13. Prop 280 Days Command Configuration
8.14. Prop to Mars Periapsis Command Configuration
8.15. Achieve BdotT Command Configuration
8.16. Achieve BdotR Command Configuration
8.17. 3D View of departure hyperbolic trajectory (EarthView)
8.18. 3D View of heliocentric transfer trajectory (SolarSystemView)
8.19. 3D View of approach hyperbolic trajectory. MAVEN stopped at periapsis (MarsView)
8.20. Mission Sequence showing first and second Target sequences
8.21. Prop for 1 day Command Configuration
8.22. Mars Capture Command Configuration
8.23. Vary MOI Parameter Selection
8.24. Vary MOI Command Configuration
8.25. Apply MOI Command Configuration
8.26. Prop to Mars Apoapsis Command Configuration
8.27. Achieve RMAG Command Configuration
8.28. 3D view of Mars Capture orbit after MOI maneuver (MarsView)
9.1. View of Lunar Flyby from Normal to Earth Equator
9.2. View of Lunar Flyby Geometry
9.3. Definition of Control and Patch Points
9.4. View of Discontinuous Trajectory
9.5. Alternate View (1) of Discontinuous Trajectory
9.6. Alternate View (2) of Discontinuous Trajectory
9.7. Smooth Trajectory Solution
9.8. Optimal Trajectory Solution
9.9. Solution Using New Guess

List of Tables

5.1. Sat Orbit State Settings
6.1. DefaultOrbitView settings
6.2. Additional Target Sequence Commands
7.1. Additional Target Sequence Commands
8.1. MainTank settings
8.2. MAVEN settings
8.3. NearEarth settings
8.4. DeepSpace settings
8.5. NearMars settings
8.6. EarthView settings
8.7. SolarSystemView settings
8.8. MarsView settings
8.9. Additional First Target Sequence Commands
8.10. Additional Second Target Sequence Commands
15. Multiple platforms
16. Windows
17. Mac OS X
18. Linux

Documentation Overview

Welcome, and thank you for using GMAT! This User Guide contains a wealth of material to introduce you to GMAT and how it works. It also provides an extensive Reference Guide that contains data on every Resource, Command, and major subcomponent in the system.

The Using GMAT chapter contains high level and introductory information on the sytem. If you need information on how to install and run the system, would like a tour of the system, want know how to configure data files, or how GMAT is organized, start here.

The Using GMAT section provides general information on GMAT and how to use the software.

The Welcome to GMAT contains a brief project and software overview, including project status, licensing, and contributors.

The Getting Started section describes how to get and install GMAT, how to run the provided samples, and where to turn for further help.

The Tour of GMAT is an in-depth guide through some of the key interface features, including the Resources tree, Mission tree, Command Summary, and Script Editor.

Note

We consider the User Interfaces Overview section to be essential reading, as it describes some fundamental aspects of how GMAT works.

The Tutorials section contains in-depth tutorials that show you how to use GMAT for end-to-end analysis. The tutorials are designed to teach you how to use GMAT in the context of performing real-world analysis and are intended to take between 30 minutes and several hours to complete. Each tutorial has a difficulty level and an approximate duration listed with any prerequisites in its introduction, and are arranged in a general order of difficulty.

Here is a summary of selected Tutorials. For a complete list of tutorials see the Tutorials chapter.

The Simulating an Orbit tutorial is the first tutorial you should take to learn how to use GMAT to solve mission design problems. You will learn how to specify an orbit and propagate to orbit periapsis.

The Mars B-Plane Targeting tutorial shows how to use GMAT to design a Mars transfer trajectory by targeting desired B-plane conditions at Mars.

The Target Finite Burn to Raise Apogee tutorial shows how to raise orbit apogee using finite maneuver targeting.

The Reference Guide contains individual topics that describe each of GMAT's resources and commands. When you need detailed information on syntax or application-specific examples for specific features, go here. It also includes system-level references that describe the script language syntax, parameter listings, external interfaces, and configuration files.

The Resources section provides general information on GMAT Resources such as Spacecraft, Propagators, Coordinate Systems, and EphemerisFiles to name just a few. Go here for details regarding syntax, options, variable ranges and data types, defaults, and expected behavior. Each section contains detailed, copy-and-paste ready examples.

The Commands section provides general information on GMAT Commands such as Maneuver, Assignment, Optimize, and Propagate to name just a few. Go here for details regarding syntax, options, variable ranges and data types, defaults, and expected behavior. Each section contains detailed, copy-and-paste ready examples.

The System section provides information on system configuration, external interfaces, the script language, and the command line interface.

Note

This document uses two typographical conventions throughout:

  • Graphical user interface (GUI) elements and resource and command names are presented in bold.

  • Filenames, script examples, and user input are presented in monospace.

Using GMAT

The Using GMAT chapter contains high level and introductory information on the sytem. If you need information on how to install and run the system, would like a tour of the system, want know how to configure data files, or how GMAT is organized, start here.

The Using GMAT section provides general information on GMAT and how to use the software.

The Welcome to GMAT contains a brief project and software overview, including project status, licensing, and contributors.

The Getting Started section describes how to get and install GMAT, how to run the provided samples, and where to turn for further help.

The Tour of GMAT is an in-depth guide through some of the key interface features, including the Resources tree, Mission tree, Command Summary, and Script Editor.

Note

We consider the User Interfaces Overview section to be essential reading, as it describes some fundamental aspects of how GMAT works.

Chapter 1. Welcome to GMAT

Do you want to go Mars but don't know when to leave or how much to bring? Do you want to study Earth protection by planning a mission to a near-Earth asteroid? The General Mission Analysis Tool (GMAT) is an open-source space mission design tool to answer just those types of questions. GMAT is designed to model and optimize spacecraft trajectories in flight regimes ranging from low Earth orbit to lunar, libration point , and deep space missions. GMAT is developed by a team of NASA, private industry, public, and private contributors and is used for real-world engineering studies, as a tool for education and public engagement, and starting in Sept. 2013 to fly operational spacecraft.

Features Overview

GMAT is a feature rich system containing high fidelity space system models, optimization and targeting, built in scripting and programming infrastructure, and customizable plots, reports and data products, to enable flexible analysis and solutions for custom and unique applications. GMAT can be driven from a fully featured, interactive GUI or from a custom script language. Here are some of GMAT’s key features broken down by feature group.

Dynamics and Environment Modelling

  • High fidelity dynamics models including harmonic gravity, drag, tides, and relativistic corrections

  • High fidelity spacecraft modeling

  • Formations and constellations

  • Impulsive and finite maneuver modeling and optimization

  • Propulsion system modeling including tanks and thrusters

  • Solar System modeling including high fidelity ephemerides, custom celestial bodies, libration points, and barycenters

  • Rich set of coordinate system including J2000, ICRF, fixed, rotating, topocentric, and many others

  • SPICE kernel propagation

  • Propagators that naturally synchronize epochs of multiple vehicles and avoid fixed step integration and interpolation

Plotting, Reporting and Product Generation

  • Interactive 3-D graphics

  • Customizable data plots and reports

  • Post computation animation

  • CCSDS and SPK ephemeris generation

Optimization and Targeting

  • Boundary value targeters

  • Nonlinear, constrained optimization

  • Custom, scriptable cost functions

  • Custom, scriptable nonlinear equality and inequality constraint functions

  • Custom targeter controls and constraints

Programming Infrastructure

  • User defined variables, arrays, and strings

  • User defined equations using MATLAB syntax. (i.e. overloaded array operation)

  • Control flow such as If, For, and While loops for custom applications

  • Matlab interface

  • Built in parameters and calculations in multiple coordinate systems

Interfaces

  • Fully featured, interactive GUI that makes simple analysis quick and easy

  • Custom scripting language that makes complex, custom analysis possible

  • Matlab interface for custom external simulations and calculations

  • Command line interface for batch analysis

Licensing

GMAT is licensed under the Apache License 2.0.

Platform Support

GMAT has been rigorously tested on the Windows 7 platform and we perform nightly regression tests running almost 11,000 test cases for the script engine and over 4000 test cases for the GUI interface.

While the system is routinely built on Mac and Linux, we consider the software to be in alpha form on those plaforms. For release R2013a, we have only addressed issues on Mac and Linux that also occur on the Windows 7 platform. Part of our planning effort for the next release will be to access the future of GMAT on Mac and Linux.

Development Status and Usage

R2013a is a major maintenance release with completely updated documentation and greatly improved quality. GMAT is no longer Beta software. Historically, solutions from GMAT have been verified in other operational systems. However, with release R2013a, the GMAT team will perform final operational certifications testing of the system be completed in the summer of 2013. After completion of operarational certification, GMAT will be used for operational support of flight projects.

GMAT has been used to optimize maneuvers for flight projects such as NASA’s LCROSS and ARTEMIS missions, and the Lunar Reconnaissance Orbiter (LRO). ARTEMIS and LRO flew trajectories optimized in GMAT and verified in the operational ground system. GMAT has been used extensively for launch window verification for OSIRIS-REx. The MMS project has used GMAT for formation maneuver planning and Monte Carlo analysis. GMAT has been used on numerous concept studies from Earth-Sun libration point missions, LEO missions, lunar missions, and interplanetary missions to Venus, Mars, Jupiter, and near-Earth and Trojan asteroids.

Contributors

The Navigation and Mission Design Branch at NASA’s Goddard Space Flight Center performs project management activities and is involved in most phases of the development process including requirements, algorithms, design, and testing. The Ground Software Systems Branch performs design, implementation, and integration testing. Commecial particpants contribute to design, implementation, testing and documentation. Commercial participants for R2013a include:

  • Thinking Systems, Inc. (system architecture and all aspects of development)

  • a.i. solutions (testing)

Past commercial and external contributors to GMAT include:

  • Air Force Research Lab (all aspects of development)

  • Boeing (algorithms and testing)

  • The Schafer Corporation (all aspects of development)

  • Honeywell Technology Solutions (testing)

  • Computer Sciences Corporation (requirements)

The NASA Jet Propulsion Laboratory (JPL) has provided funding for integration of the SPICE toolkit into GMAT. Additionally, the European Space Agency’s (ESA) Advanced Concepts team has developed optimizer plug-ins for the Non-Linear Programming (NLP) solvers SNOPT (Sparse Nonlinear OPTimizer) and IPOPT (Interior Point OPTimizer).

Chapter 2. Getting Started

Installation

Installers and application bundles are available on the GMAT SourceForge project page, located at https://sourceforge.net/projects/gmat.

The following packages are available for the major platforms:

 InstallerBinary bundleSource code
Windows (XP, Vista, 7)
Mac OS X  
Linux  

Installer

To use the Windows installer, download the appropriate gmat-winInstaller-*.exe file from the SourceForge download page and run it. You'll be asked a series of questions, and GMAT will be installed to your local user account.

By default, GMAT installs to the %LOCALAPPDATA% folder in your user directory, and does not require elevated privileges to install. On Windows Vista and Windows 7, this generally corresponds to the C:\Users\username\AppData\Local folder. You are free to choose another install location during the installation process, but elevated privileges may be required to do so.

Binary Bundle

A binary bundle is available on Windows as a .zip archive. To use it, unzip it anywhere in your file system, making sure to keep the folder structure intact. To run GMAT, run the GMAT\bin\GMAT.exe executable in the extracted folder.

Source Code

GMAT is available as a platform-independent source code bundle. Note that all testing is performed on Windows, so on other platforms it is considered a beta release. See the GMAT Wiki for compiling instructions.

Rather than compiling from the source bundle, however, we generally recommend checking out a snapshot from the Subversion repository:

svn://svn.code.sf.net/p/gmat/code

There are tags available for reach release.

Running GMAT

Starting GMAT

On Microsoft Windows platforms there are several ways to start a GMAT session. If you used the GMAT installer, you can click the GMAT R2013a item in the Start menu. If you installed GMAT from a .zip file or by compiling the system, locate the GMAT bin directory double-click GMAT.exe.

To start GMAT from the command line, run GMAT.exe. Various command-line parameters are available; see Command-Line Usage for details.

Exiting GMAT

To end a GMAT session on Windows or Linux, in the menu bar, click File, then click Exit. On Mac OS X, in the menu bar, click GMAT, then click Quit GMAT, or type Command+Q.

Sample Missions

The GMAT distribution includes more than 30 sample missions. These samples show how to apply GMAT to problems ranging from the Hohmann transfer to libration point station-keeping to trajectory optimization. To locate and run a sample mission:

  1. Open GMAT.

  2. On the toolbar click Open.

  3. Navigate to the samples folder located in the GMAT root directory.

  4. Double-click a script file of your choice.

  5. Click Run ().

To run optimization missions, you will need MATLAB and the MATLAB Optimization Toolbox or the internal libVF13Optimizer plugin. These are proprietary libraries and are not distributed with GMAT. MATLAB connectivity is not yet fully supported in the Mac and Linux, and therefore you cannot run optimization missions that use MATLAB’s fmincon optimizer on those platforms. See MATLAB Interface for details on configuring the MATLAB optimizer.

Getting Help

This User Guide provides documentation and tutorials for all of GMAT's feature. But if you have further questions, or want to provide feedback, here are some additional resources:

  • Homepage: http://gmat.gsfc.nasa.gov

  • Wiki: http://gmatcentral.org

  • User forums: http://forums.gmatcentral.org

  • Downloads and source code: http://sourceforge.net/projects/gmat

  • Submit bug reports and feature requests: http://bugs.gmatcentral.org

  • Official contact:

Chapter 3. Tour of GMAT

User Interfaces Overview

GMAT offers multiple ways to design and execute your mission. The two primary interfaces are the graphical user interface (GUI) and the script interface. These interfaces are interchangeable and each supports most of the functionality available in GMAT. When you work in the script interface, you are working in GMAT’s custom script language. To avoid issues such as circular dependencies, there are some basic rules you must follow. Below, we discuss these interfaces and then discuss the basic rules and best practices for working in each interface.

GUI Overview

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)

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:

  1. Click on the Mission tab to bring the Mission Tree to the foreground.

  2. 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

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.

Script Interface Overview

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

GMAT Script Editor

Scripts Folder

The GMAT desktop allows you to have multiple script files open simultaneously. Open script files are displayed in the Scripts folder in the Resources tree. Double click on a script in the Scripts folder to open it in the script editor. The GMAT desktop displays each script in a separate script editor. GMAT indicates the script currently represented in the GUI with a boldface name. Only one script can be loaded into the GUI at a time.

Script Status Box

The Script Status box indicates whether or not the script being edited is loaded in the GUI. The box says Active Script for the script currently represented in the GUI and Inactive Script for all others.

Save,Sync Button

The Save,Sync button saves any script file changes to disk, makes the script active, and synchronizes the GUI with the script.

Save,Sync,Run Button

The Save,Sync,Run button saves any script file changes to disk, makes the script active, synchronizes the GUI with the script, and executes the script.

Save As Button

When you click Save As, GMAT displays the Choose A File dialog box and allows you to save the script using a new file name. After saving, GMAT loads the script into the GUI, making the new file the active script.

Close

The Close button closes the script editor.

GUI/Script Interface Interactions and Rules

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.

GUI/Script Interactions and Synchronization

GMAT allows you to simultaneously edit both the script file representation and the GUI representation of your mission. It is possible to make inconsistent changes in these representations. The GUI/Script Sync Status window located in the toolbar indicates the state of the two representations. On the Mac, the status is indicated in abbreviated form in the left-hand toolbar. Synchronized (green) indicates that the script and GUI contain the same information. GUI Modified (yellow) indicates that there are changes in the GUI that have not been saved to the script. Script Modified (yellow) indicates that there are changes in the script that have not been loaded into the GUI. Unsynchronized (red) indicates that there are changes in both the script and the GUI.

Caution

GMAT will not attempt to merge or resolve simultaneous changes in the Script and GUI and you must choose which representation to save if you have made changes in both interfaces.

The Save button in the toolbar saves the GUI representation over the script. The Save,Sync button on the script editor saves the script representation and loads it into the GUI.

How the GUI Maps to a Script

Clicking the Save button in the toolbar saves the GUI representation to the script file; this is the same file you edit when working in the script editor. GUI items that appear in the Resources tree appear before the BeginMissionSequence command in a script file and are written in a predefined order. GUI items that appear in the Mission Tree appear after the BeginMissionSequence command in a script file in the same order as they appear in the GUI.

Caution

If you have a script file that has custom formatting such as spacing and data organization, you should work exclusively in the script. If you load your script into the GUI, then click Save in the toolbar, you will lose the formatting of your script. (You will not, however, lose the data.)

How the Script Maps to the GUI

Clicking the Save,Sync button on the script editor saves the script representation and loads it into the GUI. When you work in a GMAT script, you work in the raw file that GMAT reads and writes. Each script file must contain a command called BeginMissionSequence. Script lines that appear before the BeginMissionSequence command create and configure models and this data will appear in the Resources tree in the GUI. Script lines that appear after the BeginMissionSequence command define your mission sequence and appear in the Mission tree in the GUI. Here is a brief script example to illustrate:

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

The line Sat.X = 3000 sets the x-component of the Cartesian state to 3000; this value will appear on the Orbit tab of the Spacecraft dialog box. However, because the line Sat.X = 1000 appears after the BeginMissionSequence command, the line Sat.X = 1000 will appear as an assignment command in the Mission tree in the GUI.

Basic Script Syntax Rules

  • Each script file must contain one and only one BeginMissionSequence command.

  • GMAT commands are not allowed before the BeginMissionSequence command.

  • You cannot use inline math statements (equations) before the BeginMissionSequence command in a script file. (GMAT considers in-line math statements to be an assignment command. You cannot use equations in the Resources tree, so you also cannot use equations before the BeginMissionSequence command.)

  • In the GUI, you can only use in-line math statements in an assignment command. So, you cannot type 3000 + 4000 or Sat.Y - 8 in the text box for setting a spacecraft’s dry mass.

  • GMAT’s script language is case-sensitive.

    For a more complete discussion of GMAT's script language, see the Script Language documentation.

Resources Tree

The Resources tree displays GMAT resources and organizes them into logical groups and represents any objects that might be used or called in the Mission tree. This tree allows a user to add, edit, rename, or delete most available resources. The Resources tree can be edited either in the GMAT GUI or by loading or syncing a script file. All objects created in a GMAT script using a Create command are found in the Resources tree in the GMAT desktop. The default Resource tree is displayed below (Figure 3.4).

Figure 3.4. Default Resources tree

Default Resources tree

Organization

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.

Folder Menus

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 FuelTank, 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

Folder menu for Spacecraft

Figure 3.6. Folder menu for Hardware

Folder menu for Hardware

Resource Menus

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

Resource menu

Open/Close

To open a resource, you can either right-click the resource and select “Open”, or you can double click the resource. Conversely, the resource can be closed either by options in the resource properties window or selecting “Close” from the resource menu. When a resource is opened and the name is right-clicked in the Resource tree, the only options in the object menu are “Open” and “Close”.

Rename

Once a resource has been created, the user can rename it to any valid name. Valid names must begin with a letter and may be followed by any combination of letters digits and underscores. Invalid names include:

  • Folder names (eg, Spacecraft)

  • Command names (eg, Propagate)

  • Names already in use (eg, naming two variables “var”)

  • Keywords (eg, “GMAT” or “function”)

  • Names with spaces

Delete

Resources can be deleted by right clicking the object and selecting “Delete”. Resources cannot be deleted if they are used by another resource or command and an error with be thrown. For example, a Spacecraft resource cannot be deleted if one of its properties (eg. DefaultSC.A1ModJulian) is being used by the Report command. Some default objects cannot be deleted. In such cases, the Delete menu item will not be shown. They include:

  • Default coordinate systems

    • EarthMJ2000Eq

    • EarthMJ2000Ec

    • EarthFixed

    • EarthICRF

  • Default planetary bodies

    • Sun

    • Mercury

    • Venus

    • Earth

    • Luna

    • Mars

    • Jupiter

    • Saturn

    • Uranus

    • Neptune

    • Pluto

Clone

Objects can be cloned by selecting the “Clone” option in the menu. A cloned object will be an exact copy of the original object with a different name. Some objects cannot be cloned. In such cases, the Clone menu item will not be available. The only objects that cannot be cloned are:

  • Default coordinate systems (listed above)

  • Default planetary bodies (listed above)

  • Propagator resource objects

Mission Tree

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.

Warning

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, 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.

Note

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 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.

Note

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)

  • ScriptEvent commands

  • Control Flow (If, If-Else, For, and While)

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)

  • Function calls (CallMatlabFunction)

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

Note

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.

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.

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, the 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 Script Editor 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 ScriptEvent command is equivalent to showing summary data for the last command in that ScriptEvent. 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.

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 ScriptEvent command, then summary information for those commands, are not displayed. Showing Mission Summary data for a ScriptEvent is equivalent to showing summary data for the last command in that ScriptEvent. 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 the section called “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.

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

To undock the Mission Tree Display, either:

  • Right click and drag the Mission 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 undocked Mission Tree window.

  • RIght click the Mission Sequence home item and select Dock Mission Tree.

Command Summary

The Command Summary is a summary of orbit and spacecraft state information after execution of a command. For example, if the command is a Propagate command, the Command Summary contains state data after propagation is performed.

To view the Command Summary, right-click on the desired command, and select Command Summary. Or alternatively, double-click on the desired command, and click the Command Summary icon located near the lower left corner of the panel. You must run the mission before viewing Command Summary data.

Data Availability

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.

Data Contents

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.

Supported Commands

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.

Coordinate Systems

The Coordinate System menu at the top of the Command Summary dialog allows you to select the desired coordinate system for the state data. GMAT currently requires that the origin of the coordinate system is a celestial body (this will change in a future release) and the CoordinateSystem cannot reference another spacecraft.

Output Tree

The Output tree contains data files and plots after a mission is executed. Files consist of output from ReportFile and EphemerisFile resources. Plots consist of graphical OrbitView, GroundTrackPlot, and XYPlots windows.

To display the contents of an output file, double-click the name in the Output tree. A simple text display window will appear with the contents of the file.

Graphical output is automatically displayed during the mission run, but double-clicking the name of the output window in the Output tree will bring that display to the front. If you close the display window, however, you must rerun the mission to display it again.

A populated Output tree is shown in the following figure.

Script Editor

A GMAT mission can be created in either the graphical user interface (GUI), or in a text script language. When a mission is loaded into the GUI from a script, or when it is saved from the GUI, there is a script file that can be accessed from the Scripts folder in the resources tree. When you open this script, it opens in a dedicated editor window called the Script Editor. While a GMAT script can be edited in any text editor, the GMAT script editor offers more features, such as:

  • 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.

The following figure shows a basic script editor session with the major features labeled.

Figure 3.8. Parts of the script editor

Parts of the script editor

Active Script

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

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.

GUI/Script Synchronization

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:

Synchronized

The GUI and script representations are synchronized (they contain the same data).

Script Modified

The mission has been modified in the script representation, but has not been synchronized to the GUI. Use the synchronization buttons in the script editor to perform this synchronization. To revert the modifications, close the script editor without saving your changes.

GUI Modified

The mission has been modified in the GUI, but has not been synchronized to the script. To perform this synchronization, click the Save button in the GMAT toolbar. To revert the modifications, use the synchronization buttons in the script editor, or restart GMAT itself.

Unsynchronized

The mission has been modified both in the GUI and in the script. The changes cannot be merged; you have a choice of whether to save the modifications in either representations, or whether to revert either of them. See the notes above for instructions for either case.

Script Error

There is an error in the script. This puts the GUI in a minimal safe state. The error must be corrected before continuing.

Warning

Saving modifications performed in the GUI will overwrite the associated script. The data will be saved as intended, but with full detail, including fields and settings that were not explicitly listed in the original script. A copy of the original script with the extension “.bak” will be saved alongside the new version.

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:

  1. Saves any modifications to the script

  2. Closes all open windows (except the script editor itself)

  3. Validates the script file

  4. Refreshes the GUI by loading the saved script

  5. Sets GUI/Script Sync Status to Synchronized.

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.

Scripts List

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:

  • Open: opens the script in the edit window

  • Close: closes any open edit windows for this script

  • Save, Sync: opens the script and synchronizes it with the GUI, making it the active script. This is identical to the Save,Sync button in the script editor.

  • Save, Sync, Run: builds the script (see above), and also runs it. This is identical to the Save,Sync,Run button on the script editor.

  • Reload: reloads the script from the last-saved version and refreshes the script editor

  • Remove: removes the script from the script list

Edit Window

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

  • Line numbering: Line numbers along the left side of the window

  • Syntax highlighting: Certain elements of the GMAT script language are colored for immediate recognition.

  • Folding: Script blocks (like For loops, Target sequences, etc.) can be collapsed by clicking the black downward-pointing triangle to the left of the command that begins the block.

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

  • Undo/Redo: Undo or redo any number of changes since the last time the script was saved

  • Cut/Copy/Paste: Cut, copy, or paste over the current selection, or paste the current clipboard contents at the location of the cursor

  • Delete: Delete the current selection

  • Select All: Select the entire script contents

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

  • Undo/Redo: Undo or redo any number of changes since the last time the script was saved

  • Cut/Copy/Paste: Cut, copy, or paste over the current selection, or paste the current clipboard contents at the location of the cursor

  • Comment/Uncomment: Add or remove a comment symbol (%) at the beginning of the current selection

  • Select All: Select the entire script contents

  • Find/Replace: Starts the Find & Replace utility (see below)

  • Show line numbers: When selected (default), the editor window displays line numbering to the left of the script contents.

  • Goto: Place the cursor on a specific line number

  • Indent more/less: Adds or removes an indentation from the current line or selection. The default indentation is three space characters.

The following keyboard shortcuts are available when working in the script editor:

F3

Find next (when using Find & Replace)

Ctrl+A

Select all

Ctrl+C

Copy

Ctrl+F

Open Find & Replace utility

Ctrl+G

Goto

Ctrl+H

Open Find & Replace utility

Ctrl+I

Indent more

Ctrl+Shift+I

Indent less

Ctrl+R

Comment

Ctrl+T

Uncomment

Ctrl+V

Paste

Ctrl+X

Cut

Ctrl+Y

Redo

Ctrl+Z

Undo

Ctrl+mouse wheel+A

Increase or decrease script editor font size

Find and Replace

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.

File Controls

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.

Save Status Indicator

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.

Chapter 4. Configuring GMAT

Below we discuss the files and data that are distributed with GMAT and are required for GMAT execution. GMAT uses many types of data files, including planetary ephemeris files, Earth orientation data, leap second files, and gravity coefficient files. This section describes how these files are organized and the controls provided to customize them.

File Structure

The default directory structure for GMAT is broken into eight main subdirectories, as shown in Figure 4.1, “GMAT Root Directory Structure”. These directories organize the files and data used to run GMAT, including binary libraries, data files, texture maps, and 3D models. The only two files in the GMAT root directory are license.txt, which contains the text of the Apache License 2.0, and README.txt, which contains user information for the current GMAT release. A summary of the contents of each subdirectory is provided in the sections below.

Figure 4.1. GMAT Root Directory Structure

GMAT Root Directory Structure

bin

The bin directory contains all binary files required for the core functionality of GMAT. These libraries include the executable file (GMAT.exe on Windows, GMAT.app on the Mac, and GMAT on Linux) and platform-specific support libraries. The bin directory also contains two text files: gmat_startup_file.txt and gmat.ini. The startup file is discussed in detail in a separate section below. The gmat.ini file is used to configure some GUI panels, set paths to external web links, and define GUI tooltip messages.

data

The data directory contains all required data files to run GMAT and is organized according to data type, as shown in Figure 4.2, “GMAT Data Directory Structure” and described below.

Figure 4.2. GMAT Data Directory Structure

GMAT Data Directory Structure

The graphics directory contains data files for GMAT’s visualization utilities, as well as application icons and images. The splash directory contains the GMAT splash screen that is displayed briefly while GMAT is initializing. The stars directory contains a star catalogue used for displaying stars in 3D graphics. The texture folder contains texture maps used for the 2D and 3D graphics resources. The icons directory contains graphics files for icons and images loaded at run time, such as the GMAT logo and GUI icons.

The gravity directory contains gravity coefficient files for each body with a default non-spherical gravity model. Within each directory, the coefficient files are named according to the model they represent, and use the extension .cof.

The gui_config directory contains files for configuring some of the GUI dialog boxes for GMAT resources and commands. These files allow you to easily create a GUI panel for a user-provided plugin, and are also used by some of the built-in GUI panels.

The planetary_coeff directory contains the Earth orientation parameters (EOP) provided by the International Earth Rotation Service (IERS) and nutation coefficients for different nutation theories.

The planetary_ephem directory contains planetary ephemeris data in both DE and SPK formats. The de directory contains the binary digital ephemeris DE405 files for the 8 planets, the Moon, and Pluto developed and distributed by JPL. The spk directory contains the DE421 SPICE kernel and kernels for selected comets, asteroids and moons. All ephemeris files distributed with GMAT are in the little-endian format.

The time directory contains the JPL leap second kernel naif0010.tls and the GMAT leap second file tai-utc.dat.

The vehicle directory contains ephemeris data and 3D models for selected spacecraft. The ephem directory contains SPK ephemeris files, including orbit, attitude, frame, and time kernels. The models directory contains 3D model files in 3DS or POV format for use by GMAT’s OrbitView visualization resource.

docs

The docs directory contains end-user documentation, including draft PDF versions of the Mathematical Specification, Architectural Specification, and Estimation Specification. The GMAT User’s Guide is available in the help directory in PDF and HTML formats, and as a Windows HTML Help file.

extras

The extras directory contains various extra convenience files that are helpful for working with GMAT but aren't part of the core codebase. The only file here so far is a syntax coloring file for the GMAT scripting language in the Notepad++ text editor.

matlab

The matlab directory contains M-files required for GMAT’s MATLAB interfaces, including the interface to the fmincon optimizer. All files in the matlab directory and its subdirectories must be included in your MATLAB path for the MATLAB interfaces to function properly.

output

The output directory is the default location for file output such as ephemeris files and report files. If no path information is provided for reports or ephemeris files created during a GMAT session, then those files will be written to the output folder.

plugins

The plugins directory contains optional plugins that are not required for use of GMAT. The proprietary directory is used for for third-party libraries that cannot be distributed freely and is an empty folder in the open source distribution.

samples

The samples directory contains over 45 sample missions, ranging from a Hohmann transfer to libration point station-keeping to Mars B-plane targeting. Example files begin with "Ex_" and files that corresponde to GMAT tutorials begin with "Tut_". These files are intended to demonstrate GMAT’s capabilities and to provide you with a potential starting point for building common mission types for your application and flight regime. Samples with specific requirements are located in subdirectories such as NeedMatlab and NeedVF13ad.

userfunctions

The userfunctions directory contains MATLAB functions that are included in the GMAT distribution. You can also store your own custom MATLAB functions in this folders.

Configuring Data Files

You can configure the data files GMAT loads at run time by editing the gmat_startup_file.txt file located in the bin directory. The startup file contains path information for data files such as ephemeris, Earth orientation parameters and graphics files. By editing the startup file, you can customize which files are loaded and used during a GMAT session. Below we describe the customization features available in the startup file. The order of lines in the startup file does not matter.

For all details, see the Startup File reference.

Leap Second and EOP files

GMAT reads several files that are used for high fidelity modelling of time and coordinate systems: the leap second files and the Earth orientation parameters (EOP) provided by the IERS. The EOP file is updated daily by the IERS. To update your local file with the latest data, simply replace the file eopc04_08.62-now in the data/planetary_coeff directory. Updated versions of this file are available from the IERS.

There are two leap second files provided with GMAT in the data/time directory. The naif0010.tls file is used by the JPL SPICE libraries when computing ephemerides. When a new leap second is added, you can replace this file with the new file from NAIF. GMAT reads the tai-utc.dat file for all time computations requiring leap seconds that are not performed by the SPICE utilities. When a new leap second is added, you can replace this file with the new file from the US Naval Observatory. In addtion, you can modify the file if a new leap second is added by simply duplicating the last row and updating it with the correct information for the new leap second. For example, if a new leapsecond were added on 01 Jul 2013, you would add the following line to the bottom of tai-utc.dat:

2013 JUL 1 =JD 2456474.5 TAI-UTC= 35.0 S + (MJD - 41317.) X 0.0

Loading Custom Plugins

Custom plugins are loaded by adding a line to the startup file (bin/gmat_startup_file.txt) specifying the name and location of the plugin file. In order for a plugin to work with GMAT, the plugin library must be placed in the folder referenced in the startup file. For all details, see the Startup File reference.

Configuring the MATLAB Inteface

GMAT contains an interface to MATLAB. See the MATLAB Interface reference to configure the MATLAB interface.

User-defined Function Paths

If you create custom MATLAB functions, you can provide the path to those files and GMAT will locate them at run time. The default startup file is configured so you can place MATLAB functions (with a .m extension) in the userfunctions/matlab directory. GMAT automatically searches that location at run time. You can change the location of the search path to your MATLAB functions by changing these lines in your startup file to reflect the location of your files with respect to the GMAT bin folder:

MATLAB_FUNCTION_PATH = ../userfunctions/matlab

If you wish to organize your custom functions in multiple folders, you can add multiple search paths to the startup file. For example,

MATLAB_FUNCTION_PATH = ../MyFunctions/utils
MATLAB_FUNCTION_PATH = ../MyFunctions/StateConversion 
MATLAB_FUNCTION_PATH = ../MyFunctions/TimeConversion

GMAT will search the paths in the order specified in the startup file and will use the first function with a matching name.

Tutorials

The Tutorials section contains in-depth tutorials that show you how to use GMAT for end-to-end analysis. The tutorials are designed to teach you how to use GMAT in the context of performing real-world analysis and are intended to take between 30 minutes and several hours to complete. Each tutorial has a difficulty level and an approximate duration listed with any prerequisites in its introduction, and are arranged in a general order of difficulty.

Here is a summary of selected Tutorials. For a complete list of tutorials see the Tutorials chapter.

The Simulating an Orbit tutorial is the first tutorial you should take to learn how to use GMAT to solve mission design problems. You will learn how to specify an orbit and propagate to orbit periapsis.

The Mars B-Plane Targeting tutorial shows how to use GMAT to design a Mars transfer trajectory by targeting desired B-plane conditions at Mars.

The Target Finite Burn to Raise Apogee tutorial shows how to raise orbit apogee using finite maneuver targeting.

Table of Contents

5. Simulating an Orbit
Objective and Overview
Configure the Spacecraft
Rename the Spacecraft
Set the Spacecraft Epoch
Set the Keplerian Orbital Elements
Configure the Propagator
Rename the Propagator
Configure the Force Model
Configuring the Orbit View Plot
Configure the Propagate Command
Run and Analyze the Results
6. Simple Orbit Transfer
Objective and Overview
Configure Maneuvers, Differential Corrector, and Graphics
Create the Differential Corrector
Modify the Default Orbit View
Create the Maneuvers.
Configure the Mission Sequence
Configure the Initial Propagate Command
Create the Target Sequence
Create the Final Propagate Command
Configure the Target Sequence
Run the Mission
7. Target Finite Burn to Raise Apogee
Objective and Overview
Create and Configure Spacecraft Hardware and Finite Burn
Create a Thruster and a Fuel Tank
Modify Thruster1 Thrust Coefficients
Attach FuelTank1 and Thruster1 to DefaultSC
Create the Finite Burn Maneuver
Create the Differential Corrector and Target Control Variable
Configure the Mission Sequence
Configure the Initial Propagate Command
Create the Target Sequence
Configure the Target Sequence
Run the Mission
Inspect Orbit View and Message Window
Explore the Command Summary Reports
8. Mars B-Plane Targeting
Objective and Overview
Configure Fuel Tank, Spacecraft properties, Maneuvers, Propagators, Differential Corrector, Coordinate Systems and Graphics
Create Fuel Tank
Modify the DefaultSC Resource
Create the Maneuvers
Create the Propagators
Create the Differential Corrector
Create the Coordinate Systems
Create the Orbit Views
Configure the Mission Sequence
Create the First Target Sequence
Configure the First Target Sequence
Configure the Target desired B-plane Coordinates Command
Configure the Prop 3 Days Command
Configure the Prop 12 Days to TCM Command
Configure the Vary TCM.V Command
Configure the Vary TCM.N Command
Configure the Vary TCM.B Command
Configure the Apply TCM Command
Configure the Prop 280 Days Command
Configure the Prop to Mars Periapsis Command
Configure the Achieve BdotT Command
Configure the Achieve BdotR Command
Run the Mission with first Target Sequence
Create the Second Target Sequence
Create the Final Propagate Command
Configure the second Target Sequence
Configure the Mars Capture Command
Configure the Vary MOI.V Command
Configure the Apply MOI Command
Configure the Prop to Mars Apoapsis Command
Configure the Achieve RMAG Command
Run the Mission with first and second Target Sequences
9. Optimal Lunar Flyby using Multiple Shooting
Objective and Overview
Configure Coordinate Systems, Spacecraft, Optimizer, Propagators, Maneuvers, Variables, and Graphics
Create a Moon-centered Coordinate System
Create the Spacecraft
Create the Propagators
Create the Maneuvers
Create the User Variables
Create the Optimizer
Create the 3-D Graphics
Create XPPlots/Reports
Configure the Mission Sequence
Overview of the Mission Sequence
Define Initial Guesses
Initialize Variables
Vary and Set Spacecraft Epochs
Vary Control Point States
Apply Constraints at Control Points
Propagate the Segments
Compute Some Quantities and Apply Patch Constraints
Apply Patch Point Constraints
Apply Constraints on Mission Orbit
Apply Cost Function
Design the Trajectory
Overview
Step 1: Verify Your Configuration
Step 2: Find a Smooth Trajectory
Step 5: Apply a New Constraint

Chapter 5. Simulating an Orbit

Audience

Beginner

Length

30 minutes

Prerequisites

None

Script File

Tut_SimulatingAnOrbit.script

Objective and Overview

Note

The most fundamental capability of GMAT is to propagate, or simulate the orbital motion of, spacecraft. The ability to propagate spacecraft is used in nearly every practical aspect of space mission analysis, from simple orbital predictions (e.g. When will the International Space Station be over my house?) to complex analyses that determine the thruster firing sequence required to send a spacecraft to the Moon or Mars.

This tutorial will teach you how to use GMAT to propagate a spacecraft. You will learn how to configure Spacecraft and Propagator resources, and how to use the Propagate command to propagate the spacecraft to orbit periapsis, which is the point of minimum distance between the spacecraft and Earth. The basic steps in this tutorial are:

  1. Configure a Spacecraft and define its epoch and orbital elements.

  2. Configure a Propagator.

  3. Modify the default OrbitView plot to visualize the spacecraft trajectory.

  4. Modify the Propagate command to propagate the spacecraft to periapsis.

  5. Run the mission and analyze the results.

Configure the Spacecraft

In this section, you will rename the default Spacecraft and set the Spacecraft’s initial epoch and classical orbital elements. You’ll need GMAT open, with the default mission loaded. To load the default mission, click New Mission () or start a new GMAT session.

Rename the Spacecraft

  1. In the Resources tree, right-click DefaultSC and click Rename.

  2. Type Sat.

  3. Click OK.

Set the Spacecraft Epoch

  1. In the Resources tree, double-click Sat. Click the Orbit tab if it is not already selected.

  2. In the Epoch Format list, select UTCGregorian. You’ll see the value in the Epoch field change to the UTC Gregorian epoch format.

  3. In in the Epoch box, type 22 Jul 2014 11:29:10.811. This field is case-sensitive, and must be entered in the exact format shown.

  4. Click Apply or press the ENTER key to save these changes.

Set the Keplerian Orbital Elements

  1. In the StateType list, select Keplerian. In the Elements list, you will see the GUI reconfigure to display the Keplerian state representation.

  2. In the SMA box, type 83474.318.

  3. Set the remaining orbital elements as shown in the table below.

    Table 5.1. Sat Orbit State Settings

    FieldValue
    ECC0.89652
    INC12.4606
    RAAN292.8362
    AOP218.9805
    TA180


  4. Click OK.

  5. Click Save (). If this is the first time you have saved the mission, you’ll be prompted to provide a name and location for the file.

Figure 5.1. Spacecraft State Setup

Spacecraft State Setup

Configure the Propagator

In this section you’ll rename the default Propagator and configure the force model.

Rename the Propagator

  1. In the Resources tree, right-click DefaultProp and click Rename.

  2. Type LowEarthProp.

  3. Click OK.

Configure the Force Model

For this tutorial you will use an Earth 10×10 spherical harmonic model, the Jacchia-Roberts atmospheric model, solar radiation pressure, and point mass perturbations from the Sun and Moon.

  1. In the Resources tree, double-click LowEarthProp.

  2. Under Gravity, in the Degree box, type 10.

  3. In the Order box, type 10.

  4. In Atmosphere Model list, click JacchiaRoberts.

  5. Click the Select button next to the Point Masses box. This opens the CelesBodySelectDialog window.

  6. In the Available Bodies list, click Sun, then click -> to add Sun to the Selected Bodies list.

  7. Add the moon (named Luna in GMAT) in the same way.

  8. Click OK to close the CelesBodySelectDialog.

  9. Select Use Solar Radiation Pressure to toggle it on. Your screen should now match Figure 5.2, “Force Model Configuration”.

  10. Click OK.

Figure 5.2. Force Model Configuration

Force Model Configuration

Configuring the Orbit View Plot

Now you will configure an OrbitView plot so you can visualize Sat and its trajectory. The orbit of Sat is highly eccentric. To view the entire orbit at once, we need to adjust the settings of DefaultOrbitView.

  1. In the Resources tree, double-click DefaultOrbitView.

  2. In the three boxes to the right of View Point Vector, type the values -60000, 30000, and 20000 respectively.

  3. Under Drawing Option to the left, clear Draw XY Plane. Your screen should now match Figure 5.3, “DefaultOrbitView Configuration”.

  4. Click OK.

Figure 5.3. DefaultOrbitView Configuration

DefaultOrbitView Configuration

Configure the Propagate Command

This is the last step before running the mission. Below you will configure a Propagate command to propagate (or simulate the motion of) Sat to orbit periapsis.

  1. Click the Mission tab to display the Mission tree.

  2. Double-click Propagate1.

  3. Under Stopping Conditions, click the (...) button to the left of Sat.ElapsedSecs. This will display the ParameterSelectDialog window.

  4. In the Object List box, click Sat if it is not already selected. This directs GMAT to associate the stopping condition with the spacecraft Sat.

  5. In the Object Properties list, double-click Periapsis to add it to the Selected Values list. This is shown in Figure 5.4, “Propagate Command ParameterSelectDialog Configuration”.

    Figure 5.4. Propagate Command ParameterSelectDialog Configuration

    Propagate Command ParameterSelectDialog Configuration

  6. Click OK. Your screen should now match Figure 5.5, “Propagate Command Configuration”.

  7. Click OK.

Figure 5.5. Propagate Command Configuration

Propagate Command Configuration

Run and Analyze the Results

Congratulations, you have now configured your first GMAT mission and are ready to run the mission and analyze the results.

  1. Click Save () to save your mission.

  2. Click the Run ().

You will see GMAT propagate the orbit and stop at orbit periapsis. Figure 5.6, “Orbit View Plot after Mission Run” illustrates what you should see after correctly completing this tutorial. Here are a few things you can try to explore the results of this tutorial:

  1. Manipulate the DefaultOrbitView plot using your mouse to orient the trajectory so that you can to verify that at the final location the spacecraft is at periapsis. See the OrbitView reference for details.

  2. Display the command summary:

    1. Click the Mission tab to display the Mission tree.

    2. Right-click Propagate1 and select Command Summary to see data on the final state of Sat.

    3. Use the Coordinate System list to change the coordinate system in which the data is displayed.

  3. Click Start Animation () to animate the mission and watch the orbit propagate from the initial state to periapsis.

Figure 5.6. Orbit View Plot after Mission Run

Orbit View Plot after Mission Run

Chapter 6. Simple Orbit Transfer

Audience

Beginner

Length

30 minutes

Prerequisites

Complete Simulating an Orbit

Script File

Tut_SimpleOrbitTransfer.script

Objective and Overview

Note

One of the most common problems in space mission design is to design a transfer from one circular orbit to another circular orbit that lie within the same orbital plane. Circular coplanar transfers are used to raise low-Earth orbits that have degraded due to the effects of atmospheric drag. They are also used to transfer from a low-Earth orbit to a geosynchronous orbit and to send spacecraft to Mars. There is a well known sequence of maneuvers, called the Hohmann transfer, that performs a circular, coplanar transfer using the least possible amount of fuel. A Hohmann transfer employs two maneuvers. The first maneuver raises the orbital apoapsis (or lowers orbital periapsis) to the desired altitude and places the spacecraft in an elliptical transfer orbit. At the apoapsis (or periapsis) of the elliptical transfer orbit, a second maneuver is applied to circularize the orbit at the final altitude.

In this tutorial, we will use GMAT to perform a Hohmann transfer from a low-Earth parking orbit to a geosynchronous mission orbit. This requires a targeting sequence to determine the required maneuver magnitudes to achieve the desired final orbit conditions. In order to focus on the configuration of the targeter, we will make extensive use of the default configurations for spacecraft, propagators, and maneuvers.

The target sequence employs two velocity-direction maneuvers and two propagation sequences. The purpose of the first maneuver is to raise orbit apoapsis to 42,165 km, the geosynchronous radius. The purpose of the second maneuver is to nearly circularize the orbit and yield a final eccentricity of 0.005. The basic steps of this tutorial are:

  1. Create and configure a DifferentialCorrector resource.

  2. Modify the DefaultOrbitView to visualize the trajectory.

  3. Create two ImpulsiveBurn resources with default settings.

  4. Create a Target sequence to (1) raise apoapsis to geosynchronous altitude and (2) circularize the orbit.

  5. Run the mission and analyze the results.

Configure Maneuvers, Differential Corrector, and Graphics

For this tutorial, you’ll need GMAT open, with the default mission loaded. To load the default mission, click New Mission () or start a new GMAT session. We will use the default configurations for the spacecraft (DefaultSC), the propagator (DefaultProp), and the two maneuvers. DefaultSC is configured by default to a near-circular orbit, and DefaultProp is configured to use Earth as the central body with a nonspherical gravity model of degree and order 4. You may want to open the dialog boxes for these objects and inspect them more closely as we will leave them at their default settings.

Create the Differential Corrector

The Target sequence we will create later needs a DifferentialCorrector resource to operate, so let’s create one now. We'll leave the settings at their defaults.

  1. In the Resource tree, expand the Solvers folder if it isn’t already.

  2. Right-click the Boundary Value Solvers folder, point to Add, and click DifferentialCorrector. A new resource called DC1 will be created.

Modify the Default Orbit View

We need to make minor modifications to DefaultOrbitView so that the entire final orbit will fit in the graphics window.

  1. In the Resource Tree, double-click DefaultOrbitView to edit its properties.

  2. Set the values shown in the table below.

    Table 6.1. DefaultOrbitView settings

    FieldValue
    Solver Iterations, under Drawing OptionCurrent
    Axis, under View Up DefintionX
    View Point Vector boxes, under View Definition0, 0, and 120000 respectively


  3. Click OK to save these changes.

Create the Maneuvers.

We’ll need two ImpulsiveBurn resources for this tutorial, both using default values. Below, we’ll rename the default ImpulsiveBurn and create a new one.

  1. In the Resources tree, right-click DefaultIB and click Rename.

  2. In the Rename box, type TOI, an acronym for Transfer Orbit Insertion, and click OK.

  3. Right-click the Burns folder, point to Add, and click ImpulsiveBurn.

  4. Rename the new ImpulsiveBurn1 resource to GOI, an acronym for Geosynchronous Orbit Insertion.

Configure the Mission Sequence

Now we will configure a Target sequence to solve for the maneuver values required to raise the orbit to geosynchronous altitude and circularize the orbit. We’ll begin by creating an initial Propagate command, then the Target sequence itself, then the final Propagate command. To allow us to focus on the Target sequence, we’ll assume you have already learned how to propagate an orbit to a desired condition by working through the Chapter 5, Simulating an Orbit tutorial.

Configure the Initial Propagate Command

  1. Click on the Mission tab to show the Mission tree.

  2. Configure Propagate1 to propagate to DefaultSC.Earth.Periapsis.

  3. Rename Propagate1 to Prop To Periapsis.

Create the Target Sequence

Now create the commands necessary to perform the Target sequence. Figure 6.1, “Final Mission Sequence for the Hohmann Transfer” illustrates the configuration of the Mission tree after you have completed the steps in this section. We’ll discuss the Target sequence after it has been created.

Figure 6.1. Final Mission Sequence for the Hohmann Transfer

Final Mission Sequence for the Hohmann Transfer

To create the Target sequence:

  1. In the Mission tree, right-click Prop To Periapsis, point to Insert After, and click Target. This will insert two separate commands: Target1 and EndTarget1.

  2. Right-click Target1 and click Rename.

  3. Type Hohmann Transfer and click OK.

  4. Right-click Hohmann Transfer, point to Append, and click Vary.

  5. Rename Vary1 to Vary TOI.

  6. Complete the Target sequence by appending the commands in Table 6.2, “Additional Target Sequence Commands”.

    Table 6.2. Additional Target Sequence Commands

    CommandName
    ManeuverPerform TOI
    PropagateProp To Apoapsis
    AchieveAchieve RMAG = 42165
    VaryVary GOI
    ManeuverPerform GOI
    AchieveAchieve ECC = 0.005


Note

Let’s discuss what the Target sequence does. We know that two maneuvers are required to perform the Hohmann transfer. We also know that for our current mission, the final orbit radius must be 42,165 km and the final orbital eccentricity must be 0.005. However, we don’t know the size (or ΔV magnitudes) of the maneuvers that precisely achieve the desired orbital conditions. You use the Target sequence to solve for those precise maneuver values. You must tell GMAT what controls are available (in this case, two maneuvers) and what conditions must be satisfied (in this case, a specific orbital radius and eccentricity). You accomplish this using the Vary and Achieve commands. Using the Vary command, you tell GMAT what to solve for—in this case, the ΔV values for TOI and GOI. You use the Achieve command to tell GMAT what conditions the solution must satisfy—in this case, the final orbital conditions.

Create the Final Propagate Command

We need a Propagate command after the Target sequence so that we can see our final orbit.

  1. In the Mission tree, right-click End Hohmann Transfer, point to Insert After, and click Propagate. A new Propagate3 command will appear.

  2. Rename Propagate3 to Prop One Day.

  3. Double-click Prop One Day to edit its properties.

  4. Under Condition, replace the value 12000.0 with 86400, the number of seconds in one day.

  5. Click OK to save these changes.

Figure 6.2. Prop One Day Command Configuration

Prop One Day Command Configuration

Configure the Target Sequence

Now that the structure is created, we need to configure the various parts of the Target sequence to do what we want.

Configure the Vary TOI Command

  1. Double-click Vary TOI to edit its properties. Notice that the variable in the Variable box is TOI.Element1, which by default is the velocity component of TOI in the local Velocity-Normal-Binormal (VNB) coordinate system. That’s what we need, so we’ll keep it.

  2. In the Initial Value box, type 1.0.

  3. In the Max Step box, type 0.5.

  4. Click OK to save these changes.

Figure 6.3. Vary TOI Command Configuration

Vary TOI Command Configuration

Configure the Perform TOI Command

  1. Double-click Perform TOI to edit its properties. Notice that the command is already set to apply the TOI burn to the DefaultSC spacecraft, so we don’t need to change anything here.

  2. Click OK.

Figure 6.4. Perform TOI Command Configuration

Perform TOI Command Configuration

Configure the Prop to Apoapsis Command

  1. Double-click Prop to Apoapsis to edit its properties.

  2. Under Parameter, replace DefaultSC.ElapsedSecs with DefaultSC.Earth.Apoapsis.

  3. Click OK to save these changes.

Figure 6.5. Prop to Apoapsis Command Configuration

Prop to Apoapsis Command Configuration

Configure the Achieve RMAG = 42165 Command

  1. Double-click Achieve RMAG = 42165 to edit its properties.

  2. Notice that Goal is set to DefaultSC.Earth.RMAG. This is what we need, so we make no changes here.

  3. In the Value box, type 42164.169, a more precise number for the radius of a geosynchronous orbit (in kilometers).

  4. Click OK to save these changes.

Figure 6.6. Achieve RMAG = 42165 Command Configuration

Achieve RMAG = 42165 Command Configuration

Configure the Vary GOI Command

  1. Double-click Vary GOI to edit its properties.

  2. Next to Variable, click the Edit button.

  3. Under Object List, click GOI.

  4. In the Object Properties list, double-click Element1 to move it to the Selected Value(s) list. See the image below for results.

    Figure 6.7. Vary GOI Parameter Selection

    Vary GOI Parameter Selection

  5. Click OK to close the ParameterSelectDialog window.

  6. In the Initial Value box, type 1.0.

  7. In the MaxStep text box, type 0.2.

  8. Click OK to save these changes.

Figure 6.8. Vary GOI Command Configuration

Vary GOI Command Configuration

Configure the Perform GOI Command

  1. Double-click Perform GOI to edit its properties.

  2. In the Burn list, click GOI.

  3. Click OK to save these changes.

Figure 6.9. Perform GOI Command Configuration

Perform GOI Command Configuration

Configure the Achieve ECC = 0.005 Command

  1. Double-click Achieve ECC = 0.005 to edit its properties.

  2. Next to Goal, click the Edit button.

  3. In the Object Properties list, double-click ECC.

  4. Click OK to close the ParameterSelectDialog window.

  5. In the Value box, type 0.005.

  6. In the Tolerance box, type 0.0001.

  7. Click OK to save these changes.

Figure 6.10. Achieve ECC = 0.005 Command Configuration

Achieve ECC = 0.005 Command Configuration

Run the Mission

Before running the mission, click Save () and save the mission to a file of your choice. Now click Run (). As the mission runs, you will see GMAT solve the targeting problem. Each iteration and perturbation is shown in DefaultOrbitView window in light blue, and the final solution is shown in red. After the mission completes, the 3D view should appear as in to the image shown below. You may want to run the mission several times to see the targeting in progress.

Figure 6.11. 3D View of Hohmann Transfer

3D View of Hohmann Transfer

If you were to continue developing this mission, you can store the final solution of the Target sequence as the initial conditions of the TOI and GOI resources themselves, so that if you make small changes, the subsequent runs will take less time. To do this, follow these steps:

  1. In the Mission tree, double-click Hohmann Transfer to edit its properties.

  2. Click Apply Corrections.

  3. Now re-run the mission. If you inspect the results in the message window, you will see that the Target sequence converges in one iteration because you stored the solution as the initial condition.

Chapter 7. Target Finite Burn to Raise Apogee

Audience

Intermediate level

Length

45 minutes

Prerequisites

Complete Simulating an Orbit and Simple Orbit Transfer

Script File

Tut_Target_Finite_Burn_to_Raise_Apogee.script

Objective and Overview

Note

One of the most common operational problems in space mission design is the design of a finite burn that achieves a given orbital goal. A finite burn model, as opposed to the idealized impulsive burn model used for preliminary design, is needed to accurately model actual spacecraft maneuvers.

In this tutorial, we will use GMAT to perform a finite burn for a spacecraft in low Earth orbit.  The goal of this finite burn is to achieve a certain desired apogee radius.  Since the most efficient orbital location to affect apoapsis is at periapsis, the first step in this tutorial is to propagate the spacecraft to perigee.

To calculate the duration of the perigee burn needed to achieve a desired apogee radius of 12000 km, we must create the appropriate targeting sequence.  The main portion of the target sequence employs a Begin/End FiniteBurn command pair, for a velocity direction maneuver, followed by a command to propagate the spacecraft to orbit apogee.

The basic steps of this tutorial are:

  1. Create and configure the Spacecraft hardware and FiniteBurn resources

  2. Create the DifferentialCorrector and Target Control Variable

  3. Configure the Mission Sequence. To do this, we will

    1. Create Begin/End FiniteBurn commands with default settings.

    2. Create a Target sequence to achieve a 12000 km apogee radius.

  4. Run the mission and analyze the results.

Create and Configure Spacecraft Hardware and Finite Burn

For this tutorial, you’ll need GMAT open with the default mission loaded. To load the default mission, click New Mission () or start a new GMAT session. We will use the default configurations for the spacecraft (DefaultSC) and the propagator (DefaultProp). DefaultSC is configured by default to a near-circular orbit, and DefaultProp is configured to use Earth as the central body with a nonspherical gravity model of degree and order 4. You may want to open the dialog boxes for these objects and inspect them more closely as we will leave them at their default settings.

Create a Thruster and a Fuel Tank

To model thrust and fuel use associated with a finite burn, we must create a Thruster and a FuelTank and then attach the newly created FuelTank to the Thruster.

  1. In the Resources tree, right-click on the Hardware folder, point to Add, and click Thruster.  A resource named Thruster1 will be created.

  2. In the Resources tree, right-click on the Hardware folder, point to Add, and click FuelTank.  A resource named FuelTank1 will be created.

  3. Double-click Thruster1 to edit its properties.

  4. Select the Decrement Mass box so that GMAT will model fuel use associated with a finite burn.

  5. Use the drop down menu to the right of the Tank field to select FuelTank1 as the fuel source for Thruster1.  Click OK.  

Figure 7.1, “FuelTank1 Configuration” below shows the default FuelTank1 configuration that we will use and Figure 7.2, “Thruster1 Configuration” shows the finished Thruster1 configuration.

Figure 7.1. FuelTank1 Configuration

FuelTank1 Configuration

Figure 7.2. Thruster1 Configuration

Thruster1 Configuration

Note that the default Thruster1 Coordinate System, as shown in Figure 7.2, “Thruster1 Configuration”, is Earth-based Velocity, Normal, Bi-normal (VNB) and that the default Thrust Vector of (1,0,0) represents our desired velocity oriented maneuver direction.

For a general finite burn, if desired, we can specify how both the thrust and the fuel use depend upon fuel tank pressure. The user does this by inputting coefficients of certain pre-defined polynomials. To view the values for the thrust coefficients, click the Edit Thruster Coef. button and to view the ISP coefficients which determine fuel use, click the Edit Impulse Coef. button. For this tutorial, we will use the default ISP polynomial coefficient values but we will change the Thruster1 polynomial coefficients as follows.

Modify Thruster1 Thrust Coefficients

  1. In the Resources tree, double-click Thruster1 to edit its properties

  2. Click the Edit Thruster Coef. button to bring up the ThrusterCoefficientDialog box, shown in Figure 7.3, “Thruster1 Thrust Coefficients”. Replace the default C1 coefficient value of 10 with 1000. Click OK.

Figure 7.3. Thruster1 Thrust Coefficients

Thruster1 Thrust Coefficients

The exact form of the pre-defined Thrust polynomial, associated with the coefficients above, are given in the Thruster help. We note that, by default, all of the Thrust coefficients associated with terms that involve tank pressure are zero. We have kept the default zero values for all of these coefficients. We simply changed the constant term in the Thrust polynomial from 10 to 1000 which is much larger than the thrust for a typical chemical thruster. The Thrust and ISP polynomials used in this tutorial are shown below.

Thrust = 1000 (Newtons)

ISP = 300 (seconds)

Attach FuelTank1 and Thruster1 to DefaultSC

  1. In the Resources tree, double-click DefaultSC to edit its properties.

  2. Select the Tanks tab. In the Available Tanks column, select FuelTank1. Then click the right arrow button to add FuelTank1 to the SelectedTanks list. Click Apply.

  3. Select the Actuators tab. In the Available Thrusters column, select Thruster1. Then click the right arrow button to add Thruster1 to the SelectedThrusters list. Click OK.

Figure 7.4. Attach FuelTank1 to DefaultSC

Attach FuelTank1 to DefaultSC

Figure 7.5. Attach Thruster1 to DefaultSC

Attach Thruster1 to DefaultSC

Create the Finite Burn Maneuver

We’ll need a single FiniteBurn resource for this tutorial.

  1. In the Resources tree, right-click the Burns folder and add a FiniteBurn. A resource named FiniteBurn1 will be created.

  2. Double-click FiniteBurn1 to edit its properties.

  3. Use the menu to the right of the Thruster field to select Thruster1 as the thruster associated with FiniteBurn1. Click OK.

Figure 7.6. Creation of FiniteBurn Resource FiniteBurn1

Creation of FiniteBurn Resource FiniteBurn1

Create the Differential Corrector and Target Control Variable

The Target sequence we will create later needs a DifferentialCorrector resource to operate, so let’s create one now. We'll leave the settings at their defaults.

  1. In the Resources tree, expand the Solvers folder if it isn’t already.

  2. Right-click the Boundary Value Solvers folder, point to Add, and click DifferentialCorrector. A new resource called DC1 will be created.

The Target sequence we will later create uses the Vary command to adjust a user defined target control variable in order to achieve the desired orbital goal of raising apogee to 12000 km. We must first create this variable which we will name BurnDuration.

  1. In the Resources tree, right-click the Variables/Arrays/Strings folder, point to Add, and click Variable. A new window will come up with two input fields, Variable Name and Variable Value. For Variable Name, input BurnDuration and for Variable Value, input 0. Click the Create button and then the Close button.

  2. To verify that we have created this new variable correctly, double-click BurnDuration to view its properties.

Figure 7.7. Creation of Variable Resource, BurnDuration

Creation of Variable Resource, BurnDuration

Configure the Mission Sequence

Now we will configure a Target sequence to solve for the finite burn duration required to raise apogee to 12000 km. We’ll begin by creating the initial Propagate command, then the Target sequence itself.

Configure the Initial Propagate Command

  1. Click on the Mission tab to show the Mission tree.

  2. Configure Propagate1 to propagate to DefaultSC.Earth.Periapsis.

  3. Rename Propagate1 to Prop To Perigee.

Figure 7.8. Prop To Perigee Command Configuration

Prop To Perigee Command Configuration

Create the Target Sequence

Now create the commands necessary to perform the Target sequence. Figure 7.9, “Final Mission Sequence” illustrates the configuration of the Mission tree after we have completed the steps in this section. We’ll discuss the Target sequence after it has been created.

Figure 7.9. Final Mission Sequence

Final Mission Sequence

To create the Target sequence:

  1. In the Mission tree, right-click Prop To Perigee, point to Insert After, and click Target. This will insert two separate commands: Target1 and EndTarget1.

  2. Right-click Target1 and click Rename. Type Raise Apogee and click OK.

  3. Right-click Raise Apogee, point to Append, and click Vary. Rename the newly created command as Vary Burn Duration.

  4. Right-click Vary Burn Duration, point to Insert After, and click BeginFiniteBurn. Rename the newly created command as Turn Thruster On.

  5. Complete the Target sequence by inserting the commands shown in Table 7.1, “Additional Target Sequence Commands”.

Table 7.1. Additional Target Sequence Commands

CommandName
PropagateProp BurnDuration
EndFiniteBurnTurn Thruster Off
PropagateProp To Apogee
AchieveAchieve Apogee Radius = 12000

Configure the Target Sequence

Now that the structure is created, we need to configure the various parts of the Target sequence to do what we want.

Configure the Raise Apogee Command

  1. Double-click Raise Apogee to edit its properties.

  2. In the ExitMode list, click SaveAndContinue. This instructs GMAT to save the final solution of the targeting problem after you run it.

  3. Click OK to save these changes.

Figure 7.10. Raise Apogee Command Configuration

Raise Apogee Command Configuration

Configure the Vary Burn Duration Command

  1. Double-click Vary Burn Duration to edit its properties. We want this command to adjust (or “Vary”) the finite burn duration represented by the previously created control variable, BurnDuration. To accomplish this, click on the Edit button to bring up the ParameterSelectDialog. Use the ObjectType menu to select the Variable object type. The ObjectList menu will then display a list of user defined variables. Double-click on the variable, BurnDuration, so that BurnDuration appears in the SelectedValues(s) menu. Click the OK button to save the changes and return to the Vary Burn Duration command menu.

  2. In the Initial Value box, type 200

  3. In the Upper box, type 10000

  4. In the Max Step box, type 100.

  5. Click OK to save these changes.

Figure 7.11. Vary Burn Duration Command Configuration

Vary Burn Duration Command Configuration

Configure the Turn Thruster On Command

  1. Double-click Turn Thruster On to edit its properties. Notice that the command is already set to apply FiniteBurn1 to the DefaultSC spacecraft, so we don’t need to change anything here.

  2. Click OK.

Figure 7.12. Turn Thruster On Command Configuration

Turn Thruster On Command Configuration

Configure the Prop BurnDuration Command

  1. Double-click Prop BurnDuration to edit its properties.

  2. We will use the default Parameter value of DefaultSC.ElapsedSecs.

  3. Under Condition, replace the default value with Variable, BurnDuration.

  4. Click OK to save these changes.

Figure 7.13. Prop BurnDuration Command Configuration

Prop BurnDuration Command Configuration

Configure the Turn Thruster Off Command

  1. Double-click Turn Thruster Off to edit its properties. Notice that the command is already set to end FiniteBurn1 as applied to the DefaultSC spacecraft, so we don’t need to change anything here..

  2. Click OK.

Figure 7.14. Turn Thruster Off Command Configuration

Turn Thruster Off Command Configuration

Configure the Prop To Apogee Command

  1. Double-click Prop to Apogee to edit its properties.

  2. Under Parameter, replace DefaultSC.ElapsedSecs with DefaultSC.Earth.Apoapsis.

  3. Click OK to save these changes.

Figure 7.15. Prop To Apogee Command Configuration

Prop To Apogee Command Configuration

Configure the Achieve Apogee Radius = 12000 Command

  1. Double-click Achieve Apogee Radius = 12000 to edit its properties.

  2. Notice that Goal is set to DefaultSC.Earth.RMAG. This is what we need, so we make no changes here.

  3. In the Value box, type 12000

  4. Click OK to save these changes

Figure 7.16. Achieve Apogee Radius = 12000 Command Configuration

Achieve Apogee Radius = 12000 Command Configuration

Run the Mission

Before running the mission, click Save to save the mission to a file of your choice. Now click Run. As the mission runs, you will see GMAT solve the targeting problem. Each iteration and perturbation is shown in DefaultOrbitView window in light blue, and the final solution is shown in red. After the mission completes, the 3D view should appear as shown in the image shown below. You may want to run the mission several times to see the targeting in progress.

Inspect Orbit View and Message Window

Inspect the 3D DefaultOrbitView window. Manipulate the window as needed to view the orbit "face-on." Visually verify that apogee has indeed been raised.

Figure 7.17. 3D View of Finite Burn to Raise Apogee

3D View of Finite Burn to Raise Apogee

As shown below, we inspect the output message window to determine the number of iterations it took the DifferentialCorrector to converge and the final value of the control variable, BurnDuration. Verify that you obtained a similar value for BurnDuration.

*** Targeting Completed in 13 iterations

      Final Variable values:

      BurnDuration = 1213.19316329

Explore the Command Summary Reports

All of the commands in the Mission tree have associated Command Summary reports. As shown below, we review these reports to help verify that our script performed as expected.

  1. In the Mission tree, select Prop To Perigee, then right-click to open the associated Command Summary which describes the state of DefaultSC after the Prop To Perigee command has been performed. We verify perigee has indeed been achieved by finding the mean anomaly value of DefaultSC. To do this, we look at the value of MA under the Keplerian State. As expected, the mean anomaly is zero.

  2. View the Turn Thruster On command summary. Note that, as expected, prior to the start of the maneuver, the fuel mass is 756 kg.

  3. View the Turn Thruster Off command summary.

    1. Note that the mean anomaly at the end of the maneuver is 25.13 degrees. Thus, as the burn occurred, the mean anomaly increased from 0 to 25.13 degrees. By orbital theory, we know that an apogee raising burn is best performed at perigee. Thus, we may be able to achieve our orbital goal using less fuel if we “center” the burn. For example, we could try starting our burn at a mean anomaly of –(25.13/2) instead of 0 degrees.

    2. Note that, at the end of the maneuver, the fuel mass is 343.76990815648 kg. Thus, this finite burn used approximately 756 – 343.8 = 412.2 kg of fuel.

  4. View the Prop To Apogee command summary.

    1. We note that the mean anomaly is 180 degrees which proves that we are indeed at apogee.

    2. We note that the orbital radius (RMAG) is 11999.999998192 km which proves that we have achieved our desired 12000 km apogee radius to within our desired tolerance of 0.1 km.

Chapter 8. Mars B-Plane Targeting

Audience

Advanced

Length

75 minutes

Prerequisites

Complete Simulating an Orbit, Simple Orbit Transfer and a basic understanding of B-Planes and their usage in targeting is required.

Script File

Tut_Mars_B_Plane_Targeting.script

Objective and Overview

Note

One of the most challenging problems in space mission design is to design an interplanetary transfer trajectory that takes the spacecraft within a very close vicinity of the target planet. One possible approach that puts the spacecraft close to a target planet is by targeting the B-Plane of that planet. The B-Plane is a planar coordinate system that allows targeting during a gravity assist. It can be thought of as a target attached to the assisting body. In addition, it must be perpendicular to the incoming asymptote of the approach hyperbola. Figure 8.1, “Geometry of the B-Plane as seen from a viewpoint perpendicular to the B-Plane” and Figure 8.2, “The B-vector as seen from a viewpoint perpendicular to orbit plane” show the geometry of the B-Plane and B-vector as seen from a viewpoint perpendicular to orbit plane. To read more on B-Planes, please consult the GMATMathSpec document. A good example involving the use of B-Plane targeting is a mission to Mars. Sending a spacecraft to Mars can be achieved by performing a Trajectory Correction Maneuver (TCM) that targets Mars B-Plane. Once the spacecraft gets close to Mars, then an orbit insertion maneuver can be performed to capture into Mars orbit.

Figure 8.1. Geometry of the B-Plane as seen from a viewpoint perpendicular to the B-Plane

Geometry of the B-Plane as seen from a viewpoint perpendicular to the B-Plane

Figure 8.2. The B-vector as seen from a viewpoint perpendicular to orbit plane

The B-vector as seen from a viewpoint perpendicular to orbit plane

In this tutorial, we will use GMAT to model a mission to Mars. Starting from an out-going hyperbolic trajectory around Earth, we will perform a TCM to target Mars B-Plane. Once we are close to Mars, we will adjust the size of the maneuver to perform a Mars Orbit Insertion (MOI) to achieve a final elliptical orbit with an inclination of 90 degrees. Meeting these mission objectives requires us to create two separate targeting sequences. In order to focus on the configuration of the two targeters, we will make extensive use of the default configurations for spacecraft, propagators, and maneuvers.

The first target sequence employs maneuvers in the Earth-based Velocity (V), Normal (N) and Bi-normal (B) directions and includes four propagation sequences. The purpose of the maneuvers in VNB directions is to target BdotT and BdotR components of the B-vector. BdotT is targeted to 0 km and BdotR is targeted to a non-zero value to generate a polar orbit that has inclination of 90 degrees. BdotR is targeted to -7000 km to avoid having the orbit intersect Mars, which has a radius of approximately 3396 km.

The second target sequence employs a single, Mars-based anti-velocity direction (-V) maneuver and includes one propagation sequence. This single anti-velocity direction maneuver will occur at periapsis. The purpose of the maneuver is to achieve MOI by targeting position vector magnitude of 12,000 km at apoapsis. The basic steps of this tutorial are:

  1. Modify the DefaultSC to define spacecraft’s initial state. The initial state is an out-going hyperbolic trajectory that is with respect to Earth.

  2. Create and configure a Fuel Tank resource.

  3. Create two ImpulsiveBurn resources with default settings.

  4. Create and configure three Propagators: NearEarth, DeepSpace and NearMars

  5. Create and configure DifferentialCorrector resource.

  6. Create and configure three DefaultOrbitView resources to visualize Earth, Sun and Mars centered trajectories.

  7. Create and configure three CoordinateSystems: Earth, Sun and Mars centered.

  8. Create first Target sequence to target BdotT and BdotR components of the B-vector.

  9. Create second Target sequence to implement MOI by targeting position magnitude at apoapsis.

  10. Run the mission and analyze the results.

Configure Fuel Tank, Spacecraft properties, Maneuvers, Propagators, Differential Corrector, Coordinate Systems and Graphics

For this tutorial, you’ll need GMAT open, with the default mission loaded. To load the default mission, click New Mission () or start a new GMAT session. DefaultSC will be modified to set spacecraft’s initial state as an out-going hyperbolic trajectory.

Create Fuel Tank

We need to create a fuel tank in order to see how much fuel is expended after each impulsive burn. We will modify DefaultSC resource later and attach the fuel tank to the spacecraft.

  1. In the Resources tree, right-click the Hardware folder, point to Add and click Fuel Tank. A new resource called FuelTank1 will be created.

  2. Right-clickFuelTank1 and click Rename.

  3. In theRename box, type MainTank and click OK.

  4. Double click onMainTank to edit its properties.

  5. Set the values shown in the table below.

    Table 8.1. MainTank settings

    FieldValue
    Fuel Mass1718
    Fuel Density1000
    Pressure5000
    Volume2


  6. Click OK to save these changes.

Modify the DefaultSC Resource

We need to make minor modifications to DefaultSC in order to define spacecraft’s initial state and attach the fuel tank to the spacecraft.

  1. In the Resources tree, under Spacecraft folder, right-click DefaultSC and click Rename.

  2. In the Rename box, type MAVEN and click OK.

  3. Double-click on MAVEN to edit its properties. Make sure Orbit tab is selected.

  4. Set the values shown in the table below.

    Table 8.2. MAVEN settings

    FieldValue
    Epoch FormatUTCGregorian
    Epoch18 Nov 2013 20:26:24.315
    Coordinate SystemEarthMJ2000Eq
    State TypeKeplerian
    SMA under Elements-32593.21599272796
    ECC under Elements1.202872548116185
    INC under Elements28.80241266404142
    RAAN under Elements173.9693759331483
    AOP under Elements240.9696529532764
    TA under Elements359.9465533778069


  5. Click on Tanks tab now.

  6. Under Available Tanks, you'll see MainTank. This is the fuel tank that we created earlier.

  7. We attach MainTank to the spacecraft MAVEN by bringing it under Selected Tanks box. Select MainTank under Available Tanks and bring it over to the right-hand side under the Selected Tanks.

  8. Click OK to save these changes.

Create the Maneuvers

We’ll need two ImpulsiveBurn resources for this tutorial. Below, we’ll rename the default ImpulsiveBurn and create a new one. We’ll also select the fuel tank that was created earlier in order to access fuel for the burns.

  1. In the Resources tree, under the Burns folder, right-click DefaultIB and click Rename.

  2. In the Rename box, type TCM, an acronym for Trajectory Correction Maneuver and click OK to edit its properties.

  3. Double-Click TCM to edit its properties to edit its properties.

  4. Check Decrement Mass under Mass Change.

  5. For Tank field under Mass Change, select MainTank from drop down menu.

  6. Click OK to save these changes.

  7. Right-click theBurns folder, point to Add, and click ImpulsiveBurn. A new resource called ImpulsiveBurn1 will be created.

  8. Rename the new ImpulsiveBurn1 resource to MOI, an acronym for Mars Orbit Insertion and click OK.

  9. Double-click MOI to edit its properties.

  10. For Origin field under Coordinate System, select Mars.

  11. Check Decrement Mass under Mass Change.

  12. For Tank field under Mass Change, select MainTank from the drop down menu.

  13. Click OK to save these changes.

Create the Propagators

We’ll need to add three propagators for this tutorial. Below, we’ll rename the default DefaultProp and create two more propagators.

  1. In the Resources tree, under the Propagators folder, right-click DefaultProp and click Rename.

  2. In the Rename box, type NearEarth and click OK.

  3. Double-click on NearEarth to edit its properties.

  4. Set the values shown in the table below.

    Table 8.3. NearEarth settings

    FieldValue
    Initial Step Size under Integrator 600
    Accuracy under Integrator1e-013
    Min Step Size under Integrator0
    Max Step Size under Integrator600
    Model under Gravity JGM-2
    Degree under Gravity8
    Order under Gravity8
    Atmosphere Model under DragNone
    Point Masses under Force ModelAdd Luna and Sun
    Use Solar Radiation Pressure under Force ModelCheck this field


  5. Click on OK to save these changes.

  6. Right-click the Propagators folder and click Add Propagator. A new resource called Propagator1 will be created.

  7. Rename the new Propagator1 resource to DeepSpace and click OK.

  8. Double-click DeepSpace to edit its properties.

  9. Set the values shown in the table below.

    Table 8.4. DeepSpace settings

    FieldValue
    Type under Integrator PrinceDormand78
    Initial Step Size under Integrator 600
    Accuracy under Integrator1e-012
    Min Step Size under Integrator0
    Max Step Size under Integrator864000
    Central Body under Force Model Sun
    Primary Body under Force ModelNone
    Point Masses under Force ModelAdd Earth, Luna, Sun, Mars, Jupiter, Neptune, Saturn, Uranus, Venus
    Use Solar Radiation Pressure under Force ModelCheck this field


  10. Click OK to save these changes.

  11. Right-click the Propagators folder and click Add Propagator. A new resource called Propagator1 will be created.

  12. Rename the new Propagator1 resource to NearMars and click OK.

  13. Double-click on NearMars to edit its properties.

  14. Set the values shown in the table below.

    Table 8.5. NearMars settings

    FieldValue
    Type under Integrator PrinceDormand78
    Initial Step Size under Integrator 600
    Accuracy under Integrator1e-012
    Min Step Size under Integrator0
    Max Step Size under Integrator86400
    Central Body under Force Model Mars
    Primary Body under Force ModelMars
    Model under GravityMars-50C
    Degree under Gravity8
    Order under Gravity8
    Atmosphere Model under DragNone
    Point Masses under Force ModelAdd Sun
    Use Solar Radiation Pressure under Force ModelCheck this field


  15. Click OK to save the changes.

Create the Differential Corrector

Two Target sequences that we will create later need a DifferentialCorrector resource to operate, so let’s create one now. We'll leave the settings at their defaults.

  1. In the Resources tree, expand the Solvers folder if it isn’t already.

  2. Right-click the Boundary Value Solvers folder, point to Add, and click DifferentialCorrector. A new resource called DC1 will be created.

  3. Rename the new DC1 resource to DefaultDC and click OK.

Create the Coordinate Systems

The BdotT and BdotR constraints that we will define later under the first Target sequence require us to create a coordinate system. Orbit View resources that we will create later also need coordinate system resources to operate. We will create Sun and Mars centered coordinate systems. So let’s create them now.

  1. In the Resources tree, right-click the Coordinate Systems folder and click Add Coordinate System. A new Dialog box is created with a title New Coordinate System.

  2. Type SunEcliptic under Coordinate System Name box.

  3. Under Origin field, select Sun.

  4. For Type under Axes, select MJ2000Ec.

  5. Click OK to save these changes. You’ll see that a new coordinate system SunEcliptic is created under Coordinate Systems folder.

  6. Right-click the Coordinate Systems folder and click Add Coordinate System. A new Dialog Box is created with a title New Coordinate System.

  7. Type MarsInertial under Coordinate System Name box.

  8. Under Origin field, select Mars.

  9. For Type under Axes, select BodyInertial.

  10. Click OK to save these changes. You’ll see that a new coordinate system MarsInertial is created under Coordinate Systems folder.

Create the Orbit Views

We’ll need three DefaultOrbitView resources for this tutorial. Below, we’ll rename the default DefaultOrbitView and create two new ones. We need three graphics windows in order to visualize spacecraft’s trajectory centered around Earth, Sun and then Mars

  1. In the Resources tree, under Output folder, right-click DefaultOrbitView and click Rename.

  2. In the Rename box, type EarthView and click OK.

  3. In the Output folder, delete DefaultGroundTrackPlot.

  4. Double-click EarthView to edit its properties.

  5. Set the values shown in the table below.

    Table 8.6. EarthView settings

    FieldValue
    View Scale Factor under View Definition4
    View Point Vector boxes, under View Definition0, 0, 30000


  6. Click OK to save these changes.

  7. Right-click the Output folder, point to Add, and click OrbitView. A new resource called OrbitView1 will be created.

  8. Rename the new OrbitView1 resource to SolarSystemView and click OK.

  9. Double-click SolarSystemView to edit its properties.

  10. Set the values shown in the table below.

    Table 8.7. SolarSystemView settings

    FieldValue
    From Celestial Object under View Object, add following objects to Selected Celestial Object boxMars, Sun (Do not remove Earth)
    Coordinate System under View DefinitionSunEcliptic
    View Point Reference under View DefinitionSun
    View Point Vector boxes, under View Definition0, 0, 5e8
    View Direction under View DefinitionSun
    Coordinate System under View Up DefinitionSunEcliptic


  11. Click OK to save these changes.

  12. Right-click the Output folder, point to Add, and click OrbitView. A new resource called OrbitView1 will be created.

  13. Rename the new OrbitView1 resource to MarsView and click OK.

  14. Double-click MarsView to edit its properties.

  15. Set the values shown in the table below.

    Table 8.8. MarsView settings

    FieldValue
    From Celestial Object under View Object, add following object to Selected Celestial Object boxMars (You don’t have to remove Earth)
    Coordinate System under View DefinitionMarsInertial
    View Point Reference under View DefinitionMars
    View Point Vector boxes, under View Definition22000, 22000, 0
    View Direction under View DefinitionMars
    Coordinate System under View Up DefinitionMarsInertial


  16. Click OK to save the changes.

Configure the Mission Sequence

Now we will configure first Target sequence to solve for the maneuver values required to achieve BdotT and BdotR components of the B-vector. BdotT will be targeted to 0 km and BdotR is targeted to a non-zero value in order to generate a polar orbit that will have an inclination of 90 degrees. To allow us to focus on the first Target sequence, we’ll assume you have already learned how to propagate an orbit by having worked through Chapter 5, Simulating an Orbit tutorial.

The second Target sequence will perform the MOI maneuver so that the spacecraft can orbit around Mars, but that sequence will be created later.

Create the First Target Sequence

Now create the commands necessary to perform the first Target sequence. Figure 8.3, “Mission Sequence for the First Target sequence” illustrates the configuration of the Mission tree after you have completed the steps in this section. We’ll discuss the first Target sequence after it has been created.

Figure 8.3. Mission Sequence for the First Target sequence

Mission Sequence for the First Target sequence

To create the first Target sequence:

  1. Click on the Mission tab to show the Mission tree.

  2. You’ll see that there already exists a Propagate1 command. We need to delete this command

  3. Right-click on Propagate1 command and click Delete.

  4. Right-click on Mission Sequence folder, point to Append, and click Target. This will insert two separate commands: Target1 and EndTarget1.

  5. Right-click Target1 and click Rename.

  6. Type Target desired B-plane Coordinates and click OK.

  7. Right-click Target desired B-plane Coordinates, point to Append, and click Propagate. A new command called Propagate1 will be created.

  8. Right-click Propagate1 and click Rename.

  9. In the Rename box, type Prop 3 Days and click OK.

  10. Complete the Target sequence by appending the commands in Table 8.9, “Additional First Target Sequence Commands”.

    Table 8.9. Additional First Target Sequence Commands

    CommandName
    PropagateProp 12 Days to TCM
    VaryVary TCM.V
    VaryVary TCM.N
    VaryVary TCM.B
    ManeuverApply TCM
    PropagateProp 280 Days
    PropagateProp to Mars Periapsis
    AchieveAchieve BdotT
    AchieveAchieve BdotR


Note

Let’s discuss what the first Target sequence does. We know that a maneuver is required to perform the B-Plane targeting. We also know that the desired B-Plane coordinate values for BdotT and BdotR are 0 and -7000 km, resulting in a polar orbit with 90 degree inclination. However, we don’t know the size (or ΔV magnitude) and direction of the TCM maneuver that will precisely achieve the desired orbital conditions. We use the Target sequence to solve for those precise maneuver values. We must tell GMAT what controls are available (in this case, three controls associated with three components of the TCM maneuver) and what conditions must be satisfied (in this case, BdotT and BdotR values). You accomplish this by using the Vary and Achieve commands. Using the Vary command, you tell GMAT what to solve for—in this case, the ΔV value and direction for TCM. You use the Achieve command to tell GMAT what conditions the solution must satisfy—in this case, BdotT and BdotR values that result in a 90 degree inclination.

Configure the First Target Sequence

Now that the structure is created, we need to configure various parts of the first Target sequence to do what we want.

Configure the Target desired B-plane Coordinates Command

  1. 1Double-click Target desired B-plane Coordinates to edit its properties.

  2. In the ExitMode list, click SaveAndContinue. This instructs GMAT to save the final solution of the targeting problem after you run it.

  3. Click OK to save these changes.

Figure 8.4. Target desired B-plane Coordinates Command Configuration

Target desired B-plane Coordinates Command Configuration

Configure the Prop 3 Days Command

  1. Double-click Prop 3 Days to edit its properties.

  2. Under Propagator, make sure that NearEarth is selected

  3. Under Parameter, replace MAVEN.ElapsedSeconds with MAVEN.ElapsedDays.

  4. Under Condition, replace 0.0 with 3.

  5. Click OK to save these changes.

Figure 8.5. Prop 3 Days Command Configuration

Prop 3 Days Command Configuration

Configure the Prop 12 Days to TCM Command

  1. Double-click Prop 12 Days to TCM to edit its properties.

  2. Under Propagator, replace NearEarth with DeepSpace.

  3. Under Parameter, replace MAVEN.ElapsedSeconds with MAVEN.ElapsedDays.

  4. Under Condition, replace 0.0 with 12.

  5. Click OK to save these changes.

Figure 8.6. Prop 12 Days to TCM Command Configuration

Prop 12 Days to TCM Command Configuration

Configure the Vary TCM.V Command

  1. Double-click Vary TCM.V to edit its properties. Notice that the variable in the Variable box is TCM.Element1, which by default is the velocity component of TCM in the local Velocity-Normal-Binormal (VNB) coordinate system. That’s what we need, so we’ll keep it.

  2. In the Initial Value box, type 1e-005.

  3. In the Perturbation box, type 0.00001.

  4. In the Lower box, type -10e300.

  5. In the Upper box, type 10e300.

  6. In the Max Step box, type 0.002.

  7. Click OK to save these changes.

Figure 8.7. Vary TCM.V Command Configuration

Vary TCM.V Command Configuration

Configure the Vary TCM.N Command

  1. Double-click Vary TCM.N to edit its properties. Notice that the variable in the Variable box is still TCM.Element1, which by default is the velocity component of TCM in the local VNB coordinate system. We need to insert TCM.Element2 which is the normal component of TCM in the local VNB coordinate system. So let’s do that.

  2. Next to Variable, click the Edit button..

  3. Under Object List, click TCM.

  4. In the Object Properties list, double-click Element2 to move it to the Selected Value(s) list. See the image below for results.

  5. Click OK to close the ParameterSelectDialog window.

  6. Notice that the variable in the Variable box is now TCM.Element2.

  7. In the Initial Value box, type 1e-005.

  8. In the Perturbation box, type 0.00001.

  9. In the Lower box, type -10e300.

  10. In the Upper box, type 10e300.

  11. In the Max Step box, type 0.002.

  12. Click OK to save these changes.

Figure 8.8. Vary TCM.N Parameter Selection

Vary TCM.N Parameter Selection

Figure 8.9. Vary TCM.N Command Configuration

Vary TCM.N Command Configuration

Configure the Vary TCM.B Command

  1. Double-click Vary TCM.B to edit its properties. Notice that the variable in the Variable box is still TCM.Element1, which by default is the velocity component of TCM. We need to insert TCM.Element3 which is the bi-normal component of TCM in the local VNB coordinate system. So let’s do that.

  2. Next to Variable, click the Edit button.

  3. Under Object List, click TCM.

  4. In the Object Properties list, double-click Element3 to move it to the Selected Value(s) list. See the image below for results.

  5. Click OK to close the ParameterSelectDialog window.

  6. Notice that the variable in the Variable box is now TCM.Element3.

  7. In the Initial Value box, type 1e-005.

  8. In the Perturbation box, type 0.00001.

  9. In the Lower box, type -10e300.

  10. In the Upper box, type 10e300.

  11. In the Max Step box, type 0.002.

  12. Click OK to save these changes.

Figure 8.10. Vary TCM.B Parameter Selection

Vary TCM.B Parameter Selection

Figure 8.11. Vary TCM.N Command Configuration

Vary TCM.N Command Configuration

Configure the Apply TCM Command

  • Double-click Apply TCM to edit its properties. Notice that the command is already set to apply the TCM burn to the MAVEN spacecraft, so we don’t need to change anything here.

Figure 8.12. Apply TCM Command Configuration

Apply TCM Command Configuration

Configure the Prop 280 Days Command

  1. Double-click Prop 280 Days to edit its properties.

  2. Under Propagator, replace NearEarth with DeepSpace.

  3. Under Parameter, replace MAVEN.ElapsedSeconds with MAVEN.ElapsedDays.

  4. Under Condition, replace 0.0 with 280.

  5. Click OK to save these changes.

Figure 8.13. Prop 280 Days Command Configuration

Prop 280 Days Command Configuration

Configure the Prop to Mars Periapsis Command

  1. Double-click Prop to Mars Periapsis to edit its properties.

  2. Under Propagator, replace NearEarth with NearMars.

  3. Under Parameter, replace MAVEN.ElapsedSeconds with MAVEN.Mars.Periapsis.

  4. Click OK to save these changes.

Figure 8.14. Prop to Mars Periapsis Command Configuration

Prop to Mars Periapsis Command Configuration

Configure the Achieve BdotT Command

  1. Double-click Achieve BdotT to edit its properties.

  2. Next to Goal, click the Edit button.

  3. In the Object Properties list, click BdotT.

  4. Under Coordinate System, select MarsInertial and double-click on BdotT.

  5. Click OK to close the ParameterSelectDialog window.

  6. In the Value box, type 0.

  7. In the Tolerance box, type 0.00001.

  8. Click OK to save these changes.

Figure 8.15. Achieve BdotT Command Configuration

Achieve BdotT Command Configuration

Configure the Achieve BdotR Command

  1. Double-click Achieve BdotR to edit its properties.

  2. Next to Goal, click the Edit button.

  3. In the Object Properties list, click BdotR.

  4. Under Coordinate System, select MarsInertial and double-click on BdotR.

  5. Click OK to close the ParameterSelectDialog window.

  6. In the Value box, type -7000.

  7. In the Tolerance box, type 0.00001.

  8. Click OK to save these changes.

Figure 8.16. Achieve BdotR Command Configuration

Achieve BdotR Command Configuration

Run the Mission with first Target Sequence

Before running the mission, click Save () and save the mission to a file of your choice. Now click Run (). As the mission runs, you will see GMAT solve the targeting problem. Each iteration and perturbation is shown in EarthView, SolarSystemView and MarsView windows in light blue, and the final solution is shown in red. After the mission completes, the 3D views should appear as in the images shown below. You may want to run the mission several times to see the targeting in progress.

Figure 8.17. 3D View of departure hyperbolic trajectory (EarthView)

3D View of departure hyperbolic trajectory (EarthView)

Figure 8.18. 3D View of heliocentric transfer trajectory (SolarSystemView)

3D View of heliocentric transfer trajectory (SolarSystemView)

Figure 8.19. 3D View of approach hyperbolic trajectory. MAVEN stopped at periapsis (MarsView)

3D View of approach hyperbolic trajectory. MAVEN stopped at periapsis (MarsView)

Since we are going to continue developing the mission tree by creating the second Target sequence, we will store the final solution of the first Target sequence as the initial conditions of the TCM resource. This is so that when you make small changes, the subsequent runs will take less time. To do this, follow these steps:

  1. In the Mission tree, double-click Target desired B-plane Coordinates to edit its properties.

  2. Click Apply Corrections.

  3. Click OK to save these changes.

  4. Now re-run the mission. If you inspect the results in the message window, you will see that the first Target sequence converges in one iteration. This is because you stored the solution as the initial conditions.

  5. In the Mission tree, double-click Vary TCM.V, Vary TCM.N and Vary TCM.B, you will notice that the values in Initial Value box have been updated to the final solution of the first Target sequence.

If you want to know TCM maneuver’s delta-V vector values and how much fuel was expended during the maneuver, do the following steps:

  1. In the Mission tree, right-click Apply TCM, and click on Command Summary.

  2. Scroll down and under Maneuver Summary heading, values for delta-V vector are:

    Delta V Vector:

    Element 1: 0.0039376963731 km/s

    Element 2: 0.0060423170483 km/s

    Element 3: -0.0006747125434 km/s

  3. Scroll down and under Mass depletion from MainTank heading, Delta V and Mass Change tells you TCM maneuver’s magnitude and how much fuel was used for the maneuver:

    Delta V: 0.0072436375569 km/s

    Mass change: -6.3128738639690 kg

  4. Click OK to close Command Summary window.

Just to make sure that the goals of first Target sequence were met successfully, let us access command summary for Prop to Mars Periapsis command by doing the following steps:

  1. In the Mission tree, right-click Prop to Mars Periapsis, and click on Command Summary.

  2. Under Coordinate System, select MarsInertial.

  3. Under Hyperbolic Parameters heading, see the values of BdotT and BdotR. Under Keplerian State, see the value for INC. You can see that the desired B-Plane coordinates were achieved which result in a 90 degree inclined trajectory:

    BdotT = -0.0000053320678 km

    BdotR = -7000.0000019398 km

    INC = 90.000000039301 deg

Create the Second Target Sequence

Recall that we still need to create second Target sequence in order to perform Mars Orbit Insertion maneuver to achieve the desired capture orbit. In the Mission tree, we will create the second Target sequence right after the first Target sequence.

Now let’s create the commands necessary to perform the second Target sequence. Figure 8.20, “Mission Sequence showing first and second Target sequences” illustrates the configuration of the Mission tree after you have completed the steps in this section. Notice that in Figure 8.20, “Mission Sequence showing first and second Target sequences”, the second Target sequence is created after the first Target sequence. We’ll discuss the second Target sequence after it has been created.

Figure 8.20. Mission Sequence showing first and second Target sequences

Mission Sequence showing first and second Target sequences

To create the second Target sequence:

  1. Click on the Mission tab to show the Mission tree.

  2. In the Mission tree, right-click on Mission Sequence folder, point to Append, and click Target. This will insert two separate commands: Target2 and EndTarget2.

  3. Right-click Target2 and click Rename.

  4. Type Mars Capture and click OK.

  5. Right-click Mars Capture, point to Append, and click Vary. A new command called Vary4 will be created.

  6. Right-click Vary4 and click Rename.

  7. In the Rename box, type Vary MOI.V and click OK.

  8. Complete the Target sequence by appending the commands in Table 8.10, “Additional Second Target Sequence Commands”.

    Table 8.10. Additional Second Target Sequence Commands

    CommandName
    ManeuverApply MOI
    PropagateProp to Mars Apoapsis
    AchieveAchieve RMAG


Note

Let’s discuss what the second Target sequence does. We know that a maneuver is required for the Mars capture orbit. We also know that the desired radius of capture orbit at apoapsis must be 12,000 km. However, we don’t know the size (or ΔV magnitude) of the MOI maneuver that will precisely achieve the desired orbital conditions. You use the second Target sequence to solve for that precise maneuver value. You must tell GMAT what controls are available (in this case, a single maneuver) and what conditions must be satisfied (in this case, radius magnitude value). Once again, just like in the first Target sequence, here we accomplish this by using the Vary and Achieve commands. Using the Vary command, you tell GMAT what to solve for—in this case, the ΔV value for MOI. You use the Achieve command to tell GMAT what conditions the solution must satisfy—in this case, RMAG value of 12,000 km.

Create the Final Propagate Command

We need a Propagate command after the second Target sequence so that we can see our final orbit.

  1. In the Mission tree, right-click End Mars Capture, point to Insert After, and click Propagate. A new Propagate6 command will appear.

  2. Right-click Propagate6 and click Rename.

  3. Type Prop for 1 day and click OK.

  4. Double-click Prop for 1 day to edit its properties.

  5. Under Propagator, replace NearEarth with NearMars.

  6. Under Parameter, replace MAVEN.ElapsedSeconds with MAVEN.ElapsedDays.

  7. Under Condition, replace the value 0.0 with 1.

  8. Click OK to save these changes

Figure 8.21. Prop for 1 day Command Configuration

Prop for 1 day Command Configuration

Configure the second Target Sequence

Now that the structure is created, we need to configure various parts of the second Target sequence to do what we want.

Configure the Mars Capture Command

  1. Double-click Mars Capture to edit its properties.

  2. In the ExitMode list, click SaveAndContinue. This instructs GMAT to save the final solution of the targeting problem after you run it.

  3. Click OK to save these changes

Figure 8.22. Mars Capture Command Configuration

Mars Capture Command Configuration

Configure the Vary MOI.V Command

  1. Double-click Vary MOI.V to edit its properties. Notice that the variable in the Variable box is TCM.Element1. We want MOI.Element1 which is the velocity component of MOI in the local VNB coordinate system. So let’s change that.

  2. Next to Variable, click the Edit button.

  3. Under Object List, click MOI.

  4. In the Object Properties list, double-click Element1 to move it to the Selected Value(s) list. See the image below for results.

  5. Click OK to close the ParameterSelectDialog window.

  6. In the Initial Value box, type -1.0.

  7. In the Perturbation box, type 0.00001.

  8. In the Lower box, type -10e300.

  9. In the Upper box, type 10e300.

  10. In the Max Step box, type 0.1.

  11. Click OK to save these changes.

Figure 8.23. Vary MOI Parameter Selection

Vary MOI Parameter Selection

Figure 8.24. Vary MOI Command Configuration

Vary MOI Command Configuration

Configure the Apply MOI Command

  1. Double-click Apply MOI to edit its properties.

  2. In the Burn list, click MOI.

  3. Click OK to save these changes.

Figure 8.25. Apply MOI Command Configuration

Apply MOI Command Configuration

Configure the Prop to Mars Apoapsis Command

  1. Double-click Prop to Mars Apoapsis to edit its properties.

  2. Under Propagator, replace NearEarth with NearMars.

  3. Under Parameter, replace MAVEN.ElapsedSeconds with MAVEN.Mars.Apoapsis.

  4. Click OK to save these changes.

Figure 8.26. Prop to Mars Apoapsis Command Configuration

Prop to Mars Apoapsis Command Configuration

Configure the Achieve RMAG Command

  1. Double-click Achieve RMAG to edit its properties.

  2. Next to Goal, click the Edit button.

  3. In the Object Properties list, click RMAG.

  4. Under Central Body, select Mars and double-click on RMAG.

  5. Click OK to close the ParameterSelectDialog window.

  6. In the Value box, type 12000.

  7. Click OK to save these changes.

Figure 8.27. Achieve RMAG Command Configuration

Achieve RMAG Command Configuration

Run the Mission with first and second Target Sequences

Before running the mission, click Save (). This will save the additional changes that we implemented in the Mission tree. Now click Run (). The first Target sequence will converge in one-iteration. This is because earlier, we stored the solution as the initial conditions. The second Target sequence may converge after 10 to11 iterations.

As the mission runs, you will see GMAT solve the second Target sequence’s targeting problem. Each iteration and perturbation is shown in MarsView windows in light blue, and the final solution is shown in red. After the mission completes, the MarsView 3D view should appear as in the image shown below. EarthView and SolarSystemView 3D views are same as before. You may want to run the mission several times to see the targeting in progress.

Figure 8.28. 3D view of Mars Capture orbit after MOI maneuver (MarsView)

3D view of Mars Capture orbit after MOI maneuver (MarsView)

If you were to continue developing this mission, you can store the final solution of the second Target sequence as the initial condition of MOI resource. This is so that when you make small changes, the subsequent runs will take less time. To do this, follow these steps:

  1. In the Mission tree, double-click Mars Capture to edit its properties.

  2. Click Apply Corrections.

  3. Now re-run the mission. If you inspect the results in the message window, you will see that now the second Target sequence also converges in one iteration. This is because you stored the solution as the initial condition. Now whenever you re-run the mission, both first and second Target sequences will converge in just one iteration.

  4. In the Mission tree, double-click Vary MOI.V, you will notice that the values in Initial Value box have been updated to the final solution of the second Target sequence.

If you want to know MOI maneuver’s delta-V vector values and how much fuel was expended during the maneuver, do the following steps:

  1. In the Mission tree, right-click Apply MOI, and click on Command Summary.

  2. Scroll down and under Maneuver Summary heading, values for delta-V vector are:

    Delta V Vector:

    Element 1: -1.6034665169868 km/s

    Element 2: 0.0000000000000 km/s

    Element 3: 0.0000000000000 km/s

  3. Scroll down and under Mass depletion from MainTank heading, Delta V and Mass Change tells you MOI maneuver’s magnitude and how much fuel was used for the maneuver:

    Delta V: 1.6034665169868 km/s

    Mass change: -1076.0639629424 kg

Just to make sure that the goal of second Target sequence was met successfully, let us access command summary for Achieve RMAG command by doing the following steps:

  1. In the Mission tree, right-click Achieve RMAG, and click on Command Summary.

  2. Under Coordinate System, select MarsInertial.

  3. Under Keplerian State and and Spherical State headings, see the values of TA and RMAG. You can see that the desired radius of the capture orbit at apoapsis was achieved successfully:

    TA = 180.00000241484 deg

    RMAG = 12000.019889021 km

Chapter 9. Optimal Lunar Flyby using Multiple Shooting

Audience

Advanced

Length

90 minutes

Prerequisites

Complete Simulating an Orbit, Simple Orbit Transfer, Mars B-Plane Targeting tutorial and take GMAT Fundamentals training course or watch videos

Script File

Tut_MultipleShootingTutorial_Step1.script, Tut_MultipleShootingTutorial_Step2.script,... Tut_MultipleShootingTutorial_Step5.script

Objective and Overview

Note

For highly elliptic earth orbits (HEO), it is often cheaper to use the Moon’s gravity to raise periapsis or to perform plane changes, than it is to use the spacecraft’s propulsion resources. However, designing lunar flyby’s to achieve multiple specific mission constraints is non-trivial and requires modern optimization techniques to minimize fuel usage while simultaneously satisfying trajectory constraints. In this tutorial, you will learn how to design flyby trajectories by writing a GMAT script to perform multiple shooting optimization. As the analyst, your goal is to design a lunar flyby that provides a mission orbit periapsis of TBD km and changes the inclination of the mission orbit to TBD degrees. (Note: There are other mission constraints that will be discussed in more detail below.)

To efficiently solve the problem, we will employ the Multiple Shooting Method to break down the sensitive boundary value problem into smaller, less sensitive problems. We will employ three trajectory segments. The first segment will begin at Transfer Orbit Insertion (TOI) and will propagate forward; the second segment is centered at lunar periapsis and propagates both forward and backwards. The third segment is centered on Mission Orbit Insertion (MOI) and propagates forwards and backwards. See figures 1 and 2 that illustrate the final orbit solution and the “Control Points” and “Patch Points” used to solve the problem.

To begin this tutorial we start with a several views of the solution to provide a physical understanding of the problem. In Fig. 1, an illustration of a lunar flyby is shown with the trajectory displayed in red and the Moon’s orbit displayed in yellow. The Earth is at the center of the frame. We require that the following constraints are satisfied at TOI:

  1. The spacecraft is at orbit perigee,

  2. The spacecraft is at an altitude of 285 km.

  3. The inclination of the transfer orbit is 28.5 degrees.

At lunar flyby, we only require that the flyby altitude is greater than 100 km. This constraint is satisfied implicitly so we will not explicitly script this constraint. An insertion maneuver is performed at earth perigee after the lunar fly to insert into the mission orbit. The following constraints must be satisfied after MOI.

  1. The mission orbit perigee is 15 Earth radii.

  2. The mission orbit apogee is 60 Earth radii.

  3. The mission orbit inclination is 10 degrees.

Note: (Phasing with the moon is important for these orbits but design considerations for lunar phasing are beyond the scope of this tutorial)

Figure 9.1. View of Lunar Flyby from Normal to Earth Equator

View of Lunar Flyby from Normal to Earth Equator

Figure 9.2. View of Lunar Flyby Geometry

View of Lunar Flyby Geometry

Figure 3 illustrates the mission timeline and how control points and patch points are defined. Control points are drawn using a solid blue circle and are defined as locations where the state of the spacecraft is treated as an optimization variable. Patch points are drawn with an empty blue circle and are defined as locations where position and/or velocity continuity is enforced. For this tutorial, we place control points at TOI, the lunar flyby and MOI. At each patch point, the six Cartesian state elements, and the epoch are varied for a total of 18 optimization variables. At the MOI patch point, there is an additional optimization variable for the delta V to

Figure 9.3. Definition of Control and Patch Points

Definition of Control and Patch Points

Notice that while there are only three patch points, we have 5 segments (which will result in 5 spacecraft). The state at the lunar flyby, which is defined as a control point, is propagated backwards to a patch point and forwards to a patch point. The same occurs for the MOI control point. To design this trajectory, you will need to create the following GMAT resources.

  1. Create a Moon-centered coordinate system.

  2. Create 5 spacecraft required for modeling segments.

  3. Create an Earth-centered and a Moon-centered propagator.

  4. Create an impulsive maneuver.

  5. Create many user variables for use in the script.

  6. Create A VF13ad optimizer.

  7. Create plots for tracking the optimization process.

After creating the resources using script snippets you will construct the optimization sequence using GMAT script. Pseudo-code for the optimization sequence is shown below.

Define optimization initial guesses
Initialize variables
Optimize
      Loop initializations
      Vary control point epochs
      Set epochs on spacecraft
      Vary control point state values
      Configure/initialize spacecraft 
      Apply constraints on initial control points (i.e before propagation)
      Propagate spacecraft
      Apply patch point constraints
      Apply constraints on mission orbit
      Apply cost function
EndOptimize

After constructing the basic optimization sequence we will perform the following steps:

  1. Run the sequence and analyze the initial guess.

  2. Run the optimizer satisfying only the patch point constraints.

  3. Turn on the mission orbit constraints and find a feasible solution.

  4. Use the feasible solution as the initial guess and find an optimal solution.

  5. Apply an altitude constraint at lunar orbit periapsis

Configure Coordinate Systems, Spacecraft, Optimizer, Propagators, Maneuvers, Variables, and Graphics

For this tutorial, you’ll need GMAT open, with a blank script editor open. To open a blank script editor, click the New Script button in the toolbar.

Create a Moon-centered Coordinate System

You will need a Moon-centered CoordinateSystem for the lunar flyby control point so we begin by creating an inertial system centered at the moon. Use the MJ2000Eq axes for this system.

%-------------------------------------------------------------------------
% Configure coordinate systems
%-------------------------------------------------------------------------

Create CoordinateSystem MoonMJ2000Eq
MoonMJ2000Eq.Origin = Luna
MoonMJ2000Eq.Axes   = MJ2000Eq

Create the Spacecraft

You will need 5 Spacecraft for this mission design. The epoch and state information will be set in the mission sequence and here we only need to configure coordinate systems for the Spacecraft. The Spacecraft named satTOI models the transfer orbit through the first patch point. Use the EarthMJ200Eq CoordinateSystem for satTOI. satFlyBy_Forward and satFlyBy_Backward model the trajectory from the flyby backwards to patch point 1 and forward to patch point 2 respectively. Use the MoonMJ2000Eq CoordinateSystem for satFlyBy_Forward and satFlyBy_Backward. Similarly, satMOI_Forward and satMOI_Backward model the trajectory on either side of the MOI maneuver. Use the MoonMJ2000Eq CoordinateSystem for satMOI_Forward and satMOI_Backward.

%-------------------------------------------------------------------------
% Configure spacecraft
%-------------------------------------------------------------------------
%  The TOI control point
Create Spacecraft satTOI
satTOI.DateFormat                  = TAIModJulian
satTOI.CoordinateSystem            = EarthMJ2000Eq

%  Flyby control point
Create Spacecraft satFlyBy_Forward
satFlyBy_Forward.DateFormat        = TAIModJulian
satFlyBy_Forward.CoordinateSystem  = MoonMJ2000Eq

%  Flyby control point
Create Spacecraft satFlyBy_Backward
satFlyBy_Backward.DateFormat       = TAIModJulian
satFlyBy_Backward.CoordinateSystem = MoonMJ2000Eq

% MOI control point
Create Spacecraft satMOI_Backward
satMOI_Backward.DateFormat         = TAIModJulian
satMOI_Backward.CoordinateSystem   = EarthMJ2000Eq

% MOI control point
Create Spacecraft satMOI_Forward
satMOI_Forward.DateFormat          = TAIModJulian
satMOI_Forward.CoordinateSystem    = EarthMJ2000Eq

Create the Propagators

Modeling the motion of the spacecraft when near the earth and near the moon requires two propagators; one Earth-centered, and one Moon-centered. The script below configures the ForceModel named NearEarthForceModel to use JGM-2 8x8 harmonic gravity model, with point mass perturbations from the Sun and Moon, and the SRP perturbation. The ForceModel named NearMoonForceModel is similar but uses point mass gravity for all bodies. Note that the integrators are configured for performance and not for accuracy to improve run times for the tutorial. There are times when integrator accuracy can cause issues with optimizer performance due to noise in the numerical solutions.

%------------------------------------------------------------------------
% Configure propagators and force models
%-------------------------------------------------------------------------

Create ForceModel NearEarthForceModel
NearEarthForceModel.CentralBody               = Earth
NearEarthForceModel.PrimaryBodies             = {Earth}
NearEarthForceModel.PointMasses               = {Luna, Sun}
NearEarthForceModel.SRP                       = On
NearEarthForceModel.GravityField.Earth.Degree = 8
NearEarthForceModel.GravityField.Earth.Order  = 8

Create ForceModel NearMoonForceModel
NearMoonForceModel.CentralBody                = Luna
NearMoonForceModel.PointMasses                = {Luna, Earth, Sun}
NearMoonForceModel.Drag                       = None
NearMoonForceModel.SRP                        = On
Create Propagator NearEarthProp
NearEarthProp.FM = NearEarthForceModel
NearEarthProp.Type                     = PrinceDormand78
NearEarthProp.InitialStepSize          = 60
NearEarthProp.Accuracy                 = 1e-11
NearEarthProp.MinStep                  = 0.0
NearEarthProp.MaxStep                  = 86400

Create Propagator NearMoonProp
NearMoonProp.FM                        = NearMoonForceModel
NearMoonProp.Type                      = PrinceDormand78
NearMoonProp.InitialStepSize           = 60
NearMoonProp.Accuracy                  = 1e-11
NearMoonProp.MinStep                   = 0
NearMoonProp.MaxStep                   = 86400

Create the Maneuvers

We will require one ImpulsiveBurn to insert the spacecraft into the mission orbit. Define the maneuver as MOI and configure the maneuver to be applied in the VNB (Earth-referenced) Axes.

%-------------------------------------------------------------------------
% Configure maneuvers
%-------------------------------------------------------------------------
Create ImpulsiveBurn MOI
MOI.CoordinateSystem   = Local
MOI.Origin             = Earth
MOI.Axes               = VNB

Create the User Variables

IThe optimization sequence requires many user variables that will be discussed in detail later in the tutorial when we define those variables. For now, we simply create the variables (which initializes them to zero). The naming convention used here is that variables used to define constraint values begin with “con”. For example, the variable used to define the constraint on TOI inclination is called conTOIInclination. Variables beginning with “error” are used to compute constraint variances. For example, the variable used to define the error in MOI inclination is called errorTOIInclination.

%-------------------------------------------------------------------------
% Create user data: variables, arrays, strings
%-------------------------------------------------------------------------

%  Variables for defining constraint values
Create Variable conTOIPeriapsis conMOIPeriapsis conTOIInclination
Create Variable conLunarPeriapsis conMOIApoapsis conMOIInclination
Create Variable launchRdotV finalPeriapsisValue

%  Variables for computing constraint violations
Create Variable errorPos1 errorVel1 errorPos2 errorVel2 
Create Variable errorMOIRadApo errorMOIRadPer errorMOIInclination 

%  Variables for managing time calculations
Create Variable patchTwoElapsedDays patchOneEpoch patchTwoEpoch refEpoch
Create Variable launchEpoch flybyEpoch moiEpoch patchOneElapsedDays
Create Variable deltaTimeFlyBy

%  Constants and miscellaneous variables
Create Variable earthRadius earthMu launchEnergy launchVehicleDeltaV
Create Variable toiDeltaV launchCircularVelocity loopIdx Cost

Create the Optimizer

The script below creates a VF13ad optimizer provided in the Harwell Subroutine Library. VF13ad is an Sequential Quadratic Programming (SQP) optimizer that uses a line search method to solve the Non-linear Programming Problem (NLP). Here we configure the optimizer to use forward differencing to compute the derivatives, define the maximum iterations to 200, and define convergence tolerances.

%-------------------------------------------------------------------------
% Configure solvers
%-------------------------------------------------------------------------

Create VF13ad NLPOpt
NLPOpt.ShowProgress          = true
NLPOpt.ReportStyle           = Normal
NLPOpt.ReportFile            = 'VF13adVF13ad1.data'
NLPOpt.MaximumIterations     = 200
NLPOpt.Tolerance             = 1e-004
NLPOpt.UseCentralDifferences = false
NLPOpt.FeasibilityTolerance  = 0.1

Create the 3-D Graphics

You will need an OrbitView 3-D graphics window to visualize the trajectory and especially the initial guess. Below we configure an orbit view to view the entire trajectory in the EarthMJ2000Eq coordinate system. Note that we must add all five Spacecraft to the OrbitView. Updating an OrbitView during optimization can dramatically slow down the optimization process and they are best use to check initial configuration and then us XY plots to track numerical progress. Later in the tutorial, we will toggle the ShowPlot field to false once we have verified the initial configuration is correct.

Create OrbitView EarthView
EarthView.ShowPlot               = true
EarthView.SolverIterations       = All
EarthView.UpperLeft       = [ 0.4960127591706539 0.00992063492063492 ];
EarthView.Size            = [ 0.4800637958532695 0.5218253968253969 ];
EarthView.RelativeZOrder         = 501
EarthView.Add                    = ...
{satTOI, satFlyBy_Forward, satFlyBy_Backward,...
 satMOI_Backward, Earth, Luna, satMOI_Forward}
EarthView.CoordinateSystem       = EarthMJ2000Eq
EarthView.DrawObject             = [ true true true true true]
EarthView.OrbitColor   =  ...
[ 255 32768 1743054 16776960 32768 12632256 14268074 ]
EarthView.TargetColor  =  ...
[ 65280 124 4227327 255 12345 9843 16711680 ];
EarthView.DataCollectFrequency   = 1
EarthView.UpdatePlotFrequency    = 50
EarthView.NumPointsToRedraw      = 300
EarthView.ViewScaleFactor        = 35
EarthView.ViewUpAxis             = X
EarthView.UseInitialView         = On

Create XPPlots/Reports

Below we create several XYPlots and a ReportFile. We will use XYPlots to monitor the progress of the optimizer in satisfying constraints. PositionError1 plots the position error at the first patch point... VelocityError2 plots the velocity error at the second patch point, and so on. OrbitDimErrors plots the errors in the periapsis and apoapsis radii for the mission orbit. When optimization is proceeding as expected, these plots should show errors driven to zero.

Create XYPlot PositionError
PositionError.SolverIterations = All
PositionError.UpperLeft        = [ 0.02318840 0.4358208955223881 ];
PositionError.Size             = [ 0.45942028 0.5283582089552239 ];
PositionError.RelativeZOrder   = 378
PositionError.XVariable        = loopIdx
PositionError.YVariables       = {errorPos1, errorPos2}
PositionError.ShowGrid         = true
PositionError.ShowPlot         = true

Create XYPlot VelocityError
VelocityError.SolverIterations = All
VelocityError.UpperLeft        = [ 0.0246376 0.01194029850746269 ];
VelocityError.Size             = [ 0.4565217 0.4208955223880597 ];
VelocityError.RelativeZOrder   = 410
VelocityError.XVariable        = loopIdx
VelocityError.YVariables       = {errorVel1, errorVel2}
VelocityError.ShowGrid         = true
VelocityError.ShowPlot         = true

Create XYPlot OrbitDimErrors
OrbitDimErrors.SolverIterations = All
OrbitDimErrors.UpperLeft      = [ 0.4960127591706539 0.5337301587301587 ];
OrbitDimErrors.Size           = [ 0.481658692185008 0.4246031746031746 ];
OrbitDimErrors.RelativeZOrder = 347
OrbitDimErrors.XVariable      = loopIdx
OrbitDimErrors.YVariables     = {errorMOIRadApo, errorMOIRadPer}
OrbitDimErrors.ShowGrid       = true
OrbitDimErrors.ShowPlot       = true

Create XYPlot IncError
IncError.SolverIterations = All
IncError.UpperLeft        = [ 0.4953586497890296 0.01306240928882438 ];
IncError.Size             = [ 0.479324894514768 0.5079825834542816 ];
IncError.RelativeZOrder   = 382
IncError.YVariables       = {errorMOIInclination}
IncError.XVariable        = loopIdx
IncError.ShowGrid         = true
IncError.ShowPlot         = true

Create a ReportFile to allow reporting useful information to a text file for review after the optimization process is complete.

Create ReportFile debugData
debugData.SolverIterations = Current
debugData.Precision        = 16
debugData.WriteHeaders     = Off
debugData.LeftJustify      = On
debugData.ZeroFill         = Off
debugData.ColumnWidth      = 20
debugData.WriteReport      = false

Configure the Mission Sequence

Overview of the Mission Sequence

Now that the resources are created and configured, we will construct the optimization sequence. Pseudo-script for the optimization sequence is shown below. We will start by defining initial guesses for the control point optimization variables. Next, selected variables are initialized. Take some time and study the structure of the optimization loop before moving on to the next step.

Define optimization initial guesses
Initialize variables
Optimize
      Loop initializations
      Vary control point epochs
      Set epochs on spacecraft
      Vary control point state values
      Set state values on spacecraft 
      Apply constraints on control points (i.e before propagation)
      Propagate spacecraft
      Apply patch point constraints (i.e. after propagation)
      Apply constraints on mission orbit
      Apply cost function
EndOptimize

Define Initial Guesses

Below we define initial guesses for the optimization variables. Initial guesses are often difficult to generate and to ensure you can take this tutorial we have provided a reasonable initial guess for this problem. You can use GMAT to produce initial guesses and the sample script named Ex_GivenEpochGoToTheMoon distributed with GMAT can be used for that purpose for this tutorial.

The time variables launchEpoch, flybyEpoch and moiEpoch are the TAI modified Julian epochs of the launch, flyby, and MOI. It is not obvious yet that these are TAI modified Julian epochs, but later we use statements like this to set the epoch: satTOI.Epoch.TAIModJulian = launchEpoch. Recall that we previously set up the spacecraft to used coordinate systems appropriate to the problem. Setting satTOI.X sets the quantity in EarthMJ2000Eq and satFlyBy_Forward.X sets the quantity in MoonMJ2000Eq because of the configuration of the spacecraft.

BeginMissionSequence

%  Define initial guesses for optimization variables
BeginScript 'Initial Guess Values'

   toiEpoch = 27698.1612435
   flybyEpoch = 27703.7658714
   moiEpoch = 27723.305398
   satTOI.X = -6659.70273964
   satTOI.Y = -229.327053112
   satTOI.Z = -168.396030559
   satTOI.VX = 0.26826479315
   satTOI.VY = -9.54041067213
   satTOI.VZ = 5.17141415746
   satFlyBy_Forward.X = 869.478955662
   satFlyBy_Forward.Y = -6287.76679557
   satFlyBy_Forward.Z = -3598.47087228
   satFlyBy_Forward.VX = 1.14619150302
   satFlyBy_Forward.VY = -0.73648611256
   satFlyBy_Forward.VZ = -0.624051812914
   satMOI_Backward.X = -53544.9703742
   satMOI_Backward.Y = -68231.6310266
   satMOI_Backward.Z = -1272.76362793
   satMOI_Backward.VX = 2.051823425
   satMOI_Backward.VY = -1.91406286218
   satMOI_Backward.VZ = -0.280408526046
   MOI.Element1 = -0.0687322937282 

EndScript

Initialize Variables

The script below is used to define some constants and to define the values for various constraints applied to the trajectory. Pay particular attention to the constraint values and time values. For example, the variable conTOIPeriapsis defines the periapsis radius at launch constraint to be at about 285 km (geodetics will cause altitude to vary slightly). The variable conMOIApoapsis defines the mission orbit apoapsis to be 60 earth radii. The variables patchOneElapsedDays, patchTwoElapsedDays, and refEpoch are particularly important as they define the epochs of the patch points later in the script using lines like this patchOneEpoch = refEpoch + patchOneElapsedDayspatchOneEpoch. The preceding line defines the epoch of the first patch point to be one day after refEpoch (refEpoch is set to launchEpoch). Similarly, the epoch of the second patch point is defined as 13 days after refEpoch. Note, the patch point epochs can be treated as optimization variables but that was not done to reduce complexity of the tutorial.

%  Define constants and configuration settings
BeginScript 'Constants and Init'
   
   %  Some constants
   earthRadius          = 6378.1363
      
   %  Define constraint values and other constants 
   conTOIPeriapsis     = 6378 + 285   % constraint on launch periapsis
   conTOIInclination   = 28.5         % constraint launch inclination
   conLunarPeriapsis   = 8000         % constraint on flyby altitude
   conMOIApoapsis      = 60*earthRadius  % constraint on mission apoapsis
   conMOIInclination   = 10              % constraint on mission inc.
   conMOIPeriapsis     = 15*earthRadius  % constraint on mission periapsis
   patchOneElapsedDays = 1               % define epoch of patch 1
   patchTwoElapsedDays = 13              % define epoch of patch 2
   refEpoch            = launchEpoch     % ref. epoch for time quantities
   
EndScript

%  The optimization loop
Optimize 'Optimize Flyby' NLPOpt ...
   {SolveMode = Solve, ExitMode = DiscardAndContinue}
   
   %   Loop initializations
   loopIdx = loopIdx + 1
   
EndOptimize

Caution

In the above script snippet, we have included the EndOptimize command so that your script will continue to build while we construct the optimization sequence. You must paste subsequence script snippets inside of the optimization loop.

Vary and Set Spacecraft Epochs

Now we will write the commands that vary the control point epochs and apply those epochs to the spacecraft. The first three script lines below define launchEpoch, flybyEpoch, and moiEpoch to be optimization variables. It is important to note that when a Vary command is written like this

Vary NLPOpt(launchEpoch = launchEpoch, . . .

that you are telling the optimizer to vary launchEpoch (the RHS of the equal sign), and to use as the initial guess the value contained in launchEpoch when the command is first executed. This will allow us to easily change initial guess values and perform “Apply Corrections” via the script interface which will be shown later. Continuing with the script explanation, the last five lines below set the epochs of the spacecraft according to the optimization variables and set up the patch point epochs.

   %  Vary the epochs 
   Vary NLPOpt(launchEpoch = launchEpoch, ...
               {Perturbation = 0.0001, MaxStep = 0.5})
   Vary NLPOpt(flybyEpoch  = flybyEpoch, ...
               {Perturbation = 0.0001, MaxStep = 0.5})
   Vary NLPOpt(moiEpoch    = moiEpoch, ...
               {Perturbation = 0.0001, MaxStep = 0.5})

   %  Configure epochs and spacecraft
   satTOI.Epoch.TAIModJulian           = launchEpoch
   satMOI_Backward.Epoch.TAIModJulian  = moiEpoch
   satFlyBy_Forward.Epoch.TAIModJulian = flybyEpoch
   patchOneEpoch                       = refEpoch + patchOneElapsedDays
   patchTwoEpoch                       = refEpoch + patchTwoElapsedDays   

Vary Control Point States

The script below defines the control point optimization variables and defines the initial guess values for each optimization variable. For example, the following line

Vary NLPOpt(satTOI.X = satTOI.X, {Perturbation = 0.00001, MaxStep = 100})

tells GMAT to vary the X Cartesian value of satTOI using as the initial guess the value of satTOI.X at initial command execution. The Perturbation used to compute derivatives is 0.00001 and the optimizer will not take steps larger than 100 for this variable. Note: units of settings like Perturbation are the same as the unit for the optimization variable.

Notice the lines at the bottom of this script snippet that look like this:

satFlyBy_Backward = satFlyBy_Forward

This line assigns an entire Spacecraft to another Spacecraft. Because we are varying one control point in the middle of a segment, this assignment allows us to conveniently set the second Spacecraft without independently varying its state properties.

   %  Vary the states and delta V
   Vary NLPOpt(satTOI.X            = satTOI.X, ...
              {Perturbation = 0.00001, MaxStep = 100})
   Vary NLPOpt(satTOI.Y            = satTOI.Y, ...
              {Perturbation = 0.000001, MaxStep = 100})
   Vary NLPOpt(satTOI.Z            = satTOI.Z, ...
              {Perturbation = 0.00001, MaxStep = 100})
   Vary NLPOpt(satTOI.VX           = satTOI.VX, ...
              {Perturbation = 0.00001, MaxStep = 0.05})
   Vary NLPOpt(satTOI.VY           = satTOI.VY, ...
              {Perturbation = 0.000001, MaxStep = 0.05})
   Vary NLPOpt(satTOI.VZ           = satTOI.VZ, ...
              {Perturbation = 0.000001, MaxStep = 0.05})
   Vary NLPOpt(satFlyBy_Forward.X  = satFlyBy_Forward.MoonMJ2000Eq.X, ...
              {Perturbation = 0.00001, MaxStep = 100})
   Vary NLPOpt(satFlyBy_Forward.Y  = satFlyBy_Forward.MoonMJ2000Eq.Y, ...
              {Perturbation = 0.00001, MaxStep = 100})
   Vary NLPOpt(satFlyBy_Forward.Z  = satFlyBy_Forward.MoonMJ2000Eq.Z, ...
              {Perturbation = 0.00001, MaxStep = 100})
   Vary NLPOpt(satFlyBy_Forward.VX = satFlyBy_Forward.MoonMJ2000Eq.VX, ...
              {Perturbation = 0.00001, MaxStep = 0.1})
   Vary NLPOpt(satFlyBy_Forward.VY = satFlyBy_Forward.MoonMJ2000Eq.VY, ...
              {Perturbation = 0.00001, MaxStep = 0.1})
   Vary NLPOpt(satFlyBy_Forward.VZ = satFlyBy_Forward.MoonMJ2000Eq.VZ, ...
              {Perturbation = 0.00001, MaxStep = 0.1})
   Vary NLPOpt(satMOI_Backward.X   = satMOI_Backward.X, ...
              {Perturbation = 0.000001, MaxStep = 40000})
   Vary NLPOpt(satMOI_Backward.Y   = satMOI_Backward.Y, ...
              {Perturbation = 0.000001, MaxStep = 40000})
   Vary NLPOpt(satMOI_Backward.Z   = satMOI_Backward.Z, ...
              {Perturbation = 0.000001, MaxStep = 40000})
   Vary NLPOpt(satMOI_Backward.VX  = satMOI_Backward.VX, ...
              {Perturbation = 0.00001, MaxStep = 0.1})
   Vary NLPOpt(satMOI_Backward.VY  = satMOI_Backward.VY, ...
              {Perturbation = 0.00001, MaxStep = 0.1})
   Vary NLPOpt(satMOI_Backward.VZ  = satMOI_Backward.VZ, ...
              {Perturbation = 0.00001, MaxStep = 0.1})
   Vary NLPOpt(MOI.Element1        = MOI.Element1, ...
              {Perturbation = 0.0001, MaxStep = 0.005})
   
   %  Initialize spacecraft and do some reporting
   satFlyBy_Backward = satFlyBy_Forward
   satMOI_Forward    = satMOI_Backward
   deltaTimeFlyBy    = flybyEpoch - launchEpoch

Apply Constraints at Control Points

Now that the control points have been set, we can apply constraints that occur at the control points (i.e. before propagation to the patch point). Notice below that the NonlinearContraint commands are commented out. We will uncomment those constraints later. The commands below, when uncommented, will apply constraints on the launch inclination, the launch periapsis radius, the mission orbit periapsis, and the last constraint ensures that TOI occurs at periapsis of the transfer orbit.

   %  Apply constraints on initial states
   %NonlinearConstraint NLPOpt(satTOI.INC=conTOIInclination)
   %NonlinearConstraint NLPOpt(satTOI.RadPer=conTOIPeriapsis)
   %NonlinearConstraint NLPOpt(satMOI_Backward.RadPer = conMOIPeriapsis)
   errorMOIRadPer = satMOI_Backward.RadPer - conMOIPeriapsis
   
   %  This constraint ensures that satTOI state is at periapsis at injection
   launchRdotV = (satTOI.X *satTOI.VX + satTOI.Y *satTOI.VY + ...
                 satTOI.Z *satTOI.VZ)/1000
   %NonlinearConstraint NLPOpt(launchRdotV=0)

Propagate the Segments

We are now ready to propagate the spacecraft to the patch points. We must propagate satTOI forward to patchOneEpoch, propagate satFlyBy_Backward backwards to patchOneEpoch, propagate satFlyBy_Forward to patchTwoEpoch, and propagate satMOI_Backward to patchTwoEpoch. Notice that some Propagate commands are applied inside of If statements to ensure that propagation is performed in the correct direction.%

%  DO NOT PASTE THESE LINES INTO THE SCRIPT, THEY ARE 
%  INCLUDED IN THE COMPLETE SNIPPET LATER IN THIS SECTION
If satFlyBy_Forward.TAIModJulian > patchTwoEpoch
      Propagate BackProp NearMoonProp(satFlyBy_Forward) . . .
   Else
      Propagate NearMoonProp(satFlyBy_Forward) . . .
EndIf

If In the script below, you will notice like this:

%  DO NOT PASTE THESE LINES INTO THE SCRIPT, THEY ARE 
%  INCLUDED IN THE COMPLETE SNIPPET LATER IN THIS SECTION
Propagate NearEarthProp(satTOI) {satTOI.TAIModJulian = patchOneEpoch, …
PenUp EarthView    %  The next three lines handle plot epoch discontinuity 
Propagate BackProp NearMoonProp(satFlyBy_Backward)
PenDown EarthView  

These lines are used to clean up discontinuities in the OrbitView that occur because we are making discontinuous changes to time in this complex script.

   %  Propagate the segments
   Propagate NearEarthProp(satTOI) {satTOI.TAIModJulian = ...
             patchOneEpoch, StopTolerance = 1e-005}
   %  The next three lines handle epoch discontinuity in plotting
   PenUp EarthView    
   Propagate BackProp NearMoonProp(satFlyBy_Backward)
   PenDown EarthView  
   Propagate BackProp NearMoonProp(satFlyBy_Backward) ...
   {satFlyBy_Backward.TAIModJulian = patchOneEpoch, StopTolerance = 1e-005}
   
   %  Propagate FlybySat to Apogee and apply apogee constraints
   %  The next three lines handle epoch discontinuity in plotting
   PenUp EarthView    
   Propagate NearMoonProp(satFlyBy_Forward)
   PenDown EarthView
   Propagate NearMoonProp(satFlyBy_Forward)...
  {satFlyBy_Forward.Earth.Apoapsis, StopTolerance = 1e-005}
   Report debugData satFlyBy_Forward.RMAG
 
   %  Propagate FlybSat and satMOI_Backward to patchTwoEpoch
   If satFlyBy_Forward.TAIModJulian > patchTwoEpoch
      Propagate BackProp NearMoonProp(satFlyBy_Forward) ...
      {satFlyBy_Forward.TAIModJulian = patchTwoEpoch,StopTolerance=1e-005}
   Else
      Propagate NearMoonProp(satFlyBy_Forward)...
     {satFlyBy_Forward.TAIModJulian = patchTwoEpoch,StopTolerance = 1e-005}
   EndIf
   PenUp EarthView  
   %  The next three lines handle epoch discontinuity in plotting
   Propagate BackProp NearMoonProp(satMOI_Backward)
   PenDown EarthView
   Propagate BackProp NearMoonProp(satMOI_Backward)...
   {satMOI_Backward.TAIModJulian = patchTwoEpoch, StopTolerance = 1e-005}

Compute Some Quantities and Apply Patch Constraints

The variables errorPos1 and others below are used in XYPlots to display position and velocity errors at the patch points.

   %  Compute constraint errors for plots
   errorPos1 = sqrt((satTOI.X - satFlyBy_Backward.X)^2 + ...
              (satTOI.Y - satFlyBy_Backward.Y)^2 + ...
              (satTOI.Z - satFlyBy_Backward.Z)^2)
   errorVel1 = sqrt((satTOI.VX - satFlyBy_Backward.VX)^2 + ...
              (satTOI.VY - satFlyBy_Backward.VY)^2 +...
              (satTOI.VZ - satFlyBy_Backward.VZ)^2)
   errorPos2 = sqrt((satMOI_Backward.X - satFlyBy_Forward.X)^2 + ...
              (satMOI_Backward.Y - satFlyBy_Forward.Y)^2 + ...
              (satMOI_Backward.Z - satFlyBy_Forward.Z)^2)
   errorVel2 = sqrt((satMOI_Backward.VX - satFlyBy_Forward.VX)^2 + ...
              (satMOI_Backward.VY - satFlyBy_Forward.VY)^2 + ...
              (satMOI_Backward.VZ - satFlyBy_Forward.VZ)^2)
   

Apply Patch Point Constraints

The NonlinearConstraint commands below apply the patch point constraints.

   %  Apply the collocation constraints constraints on final states
   NonlinearConstraint NLPOpt(satTOI.EarthMJ2000Eq.X= ...
                       satFlyBy_Backward.EarthMJ2000Eq.X)
   NonlinearConstraint NLPOpt(satTOI.EarthMJ2000Eq.Y= ...
                       satFlyBy_Backward.EarthMJ2000Eq.Y)
   NonlinearConstraint NLPOpt(satTOI.EarthMJ2000Eq.Z= ...
                       satFlyBy_Backward.EarthMJ2000Eq.Z)
   NonlinearConstraint NLPOpt(satTOI.EarthMJ2000Eq.VX= ...
                       satFlyBy_Backward.EarthMJ2000Eq.VX)
   NonlinearConstraint NLPOpt(satTOI.EarthMJ2000Eq.VY=...
                       satFlyBy_Backward.EarthMJ2000Eq.VY)
   NonlinearConstraint NLPOpt(satTOI.EarthMJ2000Eq.VZ=...
                       satFlyBy_Backward.EarthMJ2000Eq.VZ)
   NonlinearConstraint NLPOpt(satMOI_Backward.EarthMJ2000Eq.X=...
                       satFlyBy_Forward.EarthMJ2000Eq.X)
   NonlinearConstraint NLPOpt(satMOI_Backward.EarthMJ2000Eq.Y=...
                       satFlyBy_Forward.EarthMJ2000Eq.Y)
   NonlinearConstraint NLPOpt(satMOI_Backward.EarthMJ2000Eq.Z=...
                       satFlyBy_Forward.EarthMJ2000Eq.Z)
   NonlinearConstraint NLPOpt(satMOI_Backward.EarthMJ2000Eq.VX=...
                       satFlyBy_Forward.EarthMJ2000Eq.VX)
   NonlinearConstraint NLPOpt(satMOI_Backward.EarthMJ2000Eq.VY=...
                       satFlyBy_Forward.EarthMJ2000Eq.VY)
   NonlinearConstraint NLPOpt(satMOI_Backward.EarthMJ2000Eq.VZ=...
                       satFlyBy_Forward.EarthMJ2000Eq.VZ)

Apply Constraints on Mission Orbit

We can now apply constraints on the final mission orbit that cannot be applied until after propagation. The script snippet below applies the inclination constraint on the final mission orbit, and applies the apogee radius constraint on the final mission orbit after MOI is applied.

   %  Apply mission orbit constraints and others on segments after propagation
   errorMOIInclination = satMOI_Forward.INC - conMOIInclination
   %NonlinearConstraint NLPOpt(satMOI_Forward.EarthMJ2000Eq.INC...
   % = conMOIInclination)
      %  Propagate satMOI_Forward to apogee
   %  The next three lines handle epoch discontinuity in plotting
   PenUp EarthView    
   Propagate NearEarthProp(satMOI_Forward)
   PenDown EarthView
   If satMOI_Forward.Earth.TA > 180
      Propagate NearEarthProp(satMOI_Forward) ...
      {satMOI_Forward.Earth.Periapsis}
   Else
      Propagate BackProp NearEarthProp(satMOI_Forward)...
      {satMOI_Forward.Earth.Periapsis}
   EndIf
   Maneuver MOI(satMOI_Forward)
   Propagate NearEarthProp(satMOI_Forward) {satMOI_Forward.Earth.Apoapsis}
   %NonlinearConstraint NLPOpt(satMOI_Forward.RadApo=conMOIApoapsis)
   errorMOIRadApo = satMOI_Forward.Earth.RadApo - conMOIApoapsis

Apply Cost Function

The last script snippet applies the cost function and a Stop command. The Stop command is so that we can QA your script configuration and make sure the initial guess is providing reasonable results before attempting optimization.

   %  Apply cost function and 
   Cost = sqrt( MOI.Element1^2 + MOI.Element2^2 + MOI.Element3^2)
   %Minimize NLPOpt(Cost)
   
   %  Report stuff at the end of the loop
   Report debugData MOI.Element1
   Report debugData satMOI_Forward.RMAG conMOIApoapsis conMOIInclination
   
   Stop   

Design the Trajectory

Overview

We are now ready to design the trajectory. We’ll do this in a couple of steps:

  1. Run the script configuration and verify your configuration.

  2. Run the mission applying only the patch point constraints to provide a smooth trajectory.

  3. Run the mission with all constraints applied generating an optimal solution.

  4. Run the mission with an alternative initial guess.

  5. Add a new constraint and rerun the mission.

Step 1: Verify Your Configuration

If your script is configured correctly, when you click Save-Sync-Run in the bottom of the script editor, you should see an OrbitView graphics window display the initial guess for the trajectory as shown below. In the graphics, satTOI is displayed in green, satFlyBy_Backward is displayed in orange, satFlyBy_Forward is displayed in dark red, and satMOI_Backward is displayed in bright red, and satMOI_Forward is displayed in blue.

Figure 9.4. View of Discontinuous Trajectory

View of Discontinuous Trajectory

You can use the mouse to manipulate the OrbitView to see that the patch points are indeed discontinuous for the initial guess as shown below in the two screen captures. If your configuration does not provide you with similar graphics, compare your script to the one provided for this tutorial and address any differences.

Figure 9.5. Alternate View (1) of Discontinuous Trajectory

Alternate View (1) of Discontinuous Trajectory

Figure 9.6. Alternate View (2) of Discontinuous Trajectory

Alternate View (2) of Discontinuous Trajectory

Step 2: Find a Smooth Trajectory

At this point in the tutorial, your script is configured to eliminate the patch point discontinuities but does not apply mission constraints. We need to make a few small modifications before proceeding. We will turn off the OrbitView to improve the run time, and we will remove the Stop command so that the optimizer will attempt to find a solution.

  1. Near the bottom of the script, comment out the Stop command.

  2. In the configuration of EarthView, change ShowPlot to false.

  3. Click Save Sync Run.

After a few optimizer iterations you should see “NLPOpt converged to within target accuracy" displayed in the GMAT message window and your XY plot graphics should appear as shown below. Let’s discuss the content of these windows. The upper left window shows the RSS history of velocity error at the two patch points during the optimization process. The lower left window shows the RSS history of the position error. The upper right window shows error in mission orbit inclination, and the lower right window shows error mission orbit apogee and perigee radii. You can see that in all cases the patch point discontinuities were driven to zero, but since other constraints were not applied there are still errors in some mission constraints.

Figure 9.7. Smooth Trajectory Solution

Smooth Trajectory Solution

Before proceeding to the next step, go to the message window and copy and paste the final values of the optimization variables to a text editor for later use:

Step 3: Find an Optimal Trajectory

At this point in the tutorial, your script is configured to eliminate the patch point discontinuities but does not apply constraints. We need to make a few small modifications to the script to find an solution that meets the constraints.

  1. Remove the “%” sign from the all NonlinearConstraint commands and the Minimize command:

    NonlinearConstraint NLPOpt(satTOI.INC=conTOIInclination)
    NonlinearConstraint NLPOpt(satTOI.RadPer=conTOIPeriapsis)
    NonlinearConstraint NLPOpt(satMOI_Backward.RadPer = conMOIPeriapsis)
    NonlinearConstraint NLPOpt(launchRdotV=0)
    NonlinearConstraint NLPOpt(satMOI_Forward.EarthMJ2000Eq.INC =. . .
    NonlinearConstraint NLPOpt(satMOI_Forward.RadApo=conMOIApoapsis)
    Minimize NLPOpt(Cost)
    
  2. Click Save Sync Run.

The screen capture below shows the plots after optimization has been completed. Notice that the constraint errors have been driven to zero in the plots

Figure 9.8. Optimal Trajectory Solution

Optimal Trajectory Solution

Another way to verify that the constraints have been satisfied is to look in the message window where the final constraint variances are displayed as shown below. We could further reduce the variances by lowering the tolerance setting on the optimizer.

Equality Constraint Variances:
      Delta satTOI.INC = 1.44773082411e-011
      Delta satTOI.RadPer = 7.08496372681e-010
      Delta satMOI_Backward.RadPer = -3.79732227884e-007
      Delta launchRdotV = -1.87725390788e-014
      Delta satTOI.EarthMJ2000Eq.X = 0.00037122167123
      Delta satTOI.EarthMJ2000Eq.Y = 2.79954474536e-005
      Delta satTOI.EarthMJ2000Eq.Z = 2.78138068097e-005
      Delta satTOI.EarthMJ2000Eq.VX = -3.87579257577e-009
      Delta satTOI.EarthMJ2000Eq.VY = 1.5329883335e-009
      Delta satTOI.EarthMJ2000Eq.VZ = -6.84140494256e-010
      Delta satMOI_Backward.EarthMJ2000Eq.X = 0.0327844279818
      Delta satMOI_Backward.EarthMJ2000Eq.Y = 0.0501471919124
      Delta satMOI_Backward.EarthMJ2000Eq.Z = 0.0063349630509
      Delta satMOI_Backward.EarthMJ2000Eq.VX = -7.5196416871e-008
      Delta satMOI_Backward.EarthMJ2000Eq.VY = -7.48570442854e-008
      Delta satMOI_Backward.EarthMJ2000Eq.VZ = -6.01668809219e-009
      Delta satMOI_Forward.EarthMJ2000Eq.INC = -1.25488952563e-010
      Delta satMOI_Forward.RadApo = -0.000445483252406

Finally, let’s look at the delta-V of the solution. In this case the delta-V is simply the value of MOI.Element1 which is displayed in the message window with a value of -0.09171 km/s.

Step 4: Use a New Initial Guess

In Step 2 above, you saved the final solution for the smooth trajectory run. Let’s use those values as the initial guess and see if we find a similar solution as found in the previous step. In the ScriptEvent that defines the initial guess, paste the values below, below the values already there. (don’t overwrite the old values!). Once you have changed the guess, run the mission again.

launchEpoch = 27698.2503232
flybyEpoch = 27703.7774182
moiEpoch = 27723.6487435
satTOI.X = -6651.63393843
satTOI.Y = -229.372171037
satTOI.Z = -168.481408909
satTOI.VX = 0.244028352166
satTOI.VY = -9.56544906767
satTOI.VZ = 5.11103080924
satFlyBy_Forward.X = 869.368923086
satFlyBy_Forward.Y = -6284.53685414
satFlyBy_Forward.Z = -3598.94426638
satFlyBy_Forward.VX = 1.14614444527
satFlyBy_Forward.VY = -0.726070354598
satFlyBy_Forward.VZ = -0.617780594192
satMOI_Backward.X = -53541.9714485
satMOI_Backward.Y = -68231.6304631
satMOI_Backward.Z = -1272.77554803
satMOI_Backward.VX = 2.0799329871
satMOI_Backward.VY = -1.89082570193
satMOI_Backward.VZ = -0.284385092038

We see in this case the optimization converged and found essentially the same solution of -0.0907079 km/s

Figure 9.9. Solution Using New Guess

Solution Using New Guess

Step 5: Apply a New Constraint

We leave it as an exercise, to apply a constraint that the lunar flyby periapsis radius must be greater than or equal to 5000 km.

Reference Guide

The Reference Guide contains individual topics that describe each of GMAT's resources and commands. When you need detailed information on syntax or application-specific examples for specific features, go here. It also includes system-level references that describe the script language syntax, parameter listings, external interfaces, and configuration files.

The Resources section provides general information on GMAT Resources such as Spacecraft, Propagators, Coordinate Systems, and EphemerisFiles to name just a few. Go here for details regarding syntax, options, variable ranges and data types, defaults, and expected behavior. Each section contains detailed, copy-and-paste ready examples.

The Commands section provides general information on GMAT Commands such as Maneuver, Assignment, Optimize, and Propagate to name just a few. Go here for details regarding syntax, options, variable ranges and data types, defaults, and expected behavior. Each section contains detailed, copy-and-paste ready examples.

The System section provides information on system configuration, external interfaces, the script language, and the command line interface.

Table of Contents

I. Resources
Array — A user-defined one- or two-dimensional array variable
Barycenter — The center of mass of selected celestial bodies
CelestialBody — A celestial body model
CoordinateSystem — An axis and origin pair
DifferentialCorrector — A numerical solver
EphemerisFile — Generate spacecraft’s ephemeris data
FiniteBurn — A finite burn
FminconOptimizer — The Sequential Quadratic Processor (SQP) optimizer, fmincon
Formation — A collection of spacecraft.
FuelTank — Model of a chemical fuel tank
GroundStation — A ground station model.
GroundTrackPlot — A user-defined resource that draws longitude and latitude time-history of a spacecraft
ImpulsiveBurn — An impulsive maneuver
LibrationPoint — An equilibrium point in the circular, restricted 3-body problem
MatlabFunction — Declaration of an external MATLAB function
OrbitView — A user-defined resource that plots 3-Dimensional trajectories
Propagator — A propagator models spacecraft motion
ReportFile — Report data to a text file
SolarSystem — High level solar system configuration options
Spacecraft — A spacecraft model
Spacecraft Attitude — The spacecraft attitude model
Spacecraft Ballistic/Mass Properties — The physical properties of the spacecraft
Spacecraft Epoch — The spacecraft epoch
Spacecraft Hardware — Add hardware to a spacecraft
Spacecraft Orbit State — The orbital initial conditions
Spacecraft Visualization Properties — The visual properties of the spacecraft
String — A user-defined string variable
Thruster — A chemical thruster model
Variable — A user-defined numeric variable
VF13ad — The Sequential Quadratic Processor (SQP) optimizer, VF13ad
XYPlot — Plots data onto the X and Y axes of a graph
II. Commands
Achieve — Specify a goal for a Target sequence
Assignment (=) — Set a variable or resource field to a value, possibly using mathematical expressions
BeginFiniteBurn — Model finite thrust maneuvers
BeginMissionSequence — Begin the mission sequence portion of a script
BeginScript — Execute free-form script commands
CallMatlabFunction — Call a MATLAB function
ClearPlot — Allows you to clear all data from an XYPlot
EndFiniteBurn — Model finite thrust maneuvers in the mission sequence
Equation — Perform an equation command
For — Execute a series of commands a specified number of times
If — Conditionally execute a series of commands
Maneuver — Perform an impulsive (instantaneous) maneuver
MarkPoint — Allows you to add a special mark point character on an XYPlot
Minimize — Define the cost function to minimize
NonlinearConstraint — Specify a constraint used during optimization
Optimize — Solve for condition(s) by varying one or more parameters
PenUpPenDown — Allows you to stop or begin drawing data on a plot
Propagate — Propagates spacecraft to a requested stopping condition
Report — Allows you to write data to a text file
Stop — Stop mission execution
Target — Solve for condition(s) by varying one or more parameters
Toggle — Allows you to turn data output off or on
Vary — Specifies variables used by a solver
While — Execute a series of commands repeatedly while a condition is met
III. System
Calculation Parameters — Resource properties available for use by commands and output
Command-Line Usage — Starting the GMAT application from the command line
MATLAB Interface — Interface to MATLAB system
Script Language — The GMAT script language
Startup File — The gmat_startup_file.txt configuration file

Resources


Table of Contents

Array — A user-defined one- or two-dimensional array variable
Barycenter — The center of mass of selected celestial bodies
CelestialBody — A celestial body model
CoordinateSystem — An axis and origin pair
DifferentialCorrector — A numerical solver
EphemerisFile — Generate spacecraft’s ephemeris data
FiniteBurn — A finite burn
FminconOptimizer — The Sequential Quadratic Processor (SQP) optimizer, fmincon
Formation — A collection of spacecraft.
FuelTank — Model of a chemical fuel tank
GroundStation — A ground station model.
GroundTrackPlot — A user-defined resource that draws longitude and latitude time-history of a spacecraft
ImpulsiveBurn — An impulsive maneuver
LibrationPoint — An equilibrium point in the circular, restricted 3-body problem
MatlabFunction — Declaration of an external MATLAB function
OrbitView — A user-defined resource that plots 3-Dimensional trajectories
Propagator — A propagator models spacecraft motion
ReportFile — Report data to a text file
SolarSystem — High level solar system configuration options
Spacecraft — A spacecraft model
Spacecraft Attitude — The spacecraft attitude model
Spacecraft Ballistic/Mass Properties — The physical properties of the spacecraft
Spacecraft Epoch — The spacecraft epoch
Spacecraft Hardware — Add hardware to a spacecraft
Spacecraft Orbit State — The orbital initial conditions
Spacecraft Visualization Properties — The visual properties of the spacecraft
String — A user-defined string variable
Thruster — A chemical thruster model
Variable — A user-defined numeric variable
VF13ad — The Sequential Quadratic Processor (SQP) optimizer, VF13ad
XYPlot — Plots data onto the X and Y axes of a graph

Array

Array — A user-defined one- or two-dimensional array variable

Description

The Array resource is used to store a one- or two-dimensional set of numeric values, such as a vector or a matrix. Individual elements of an array can be used in place of a literal numeric value in most commands.

Arrays must be dimensioned at the time of creation, using the following syntax:

Create Array anArray[rows, columns]

If only one dimension is specified, a row vector is created.

Array values are initialized to zero at creation. Values can be assigned individually using literal numeric values or (in the Mission Sequence) Variable resources, Array resource elements, resource parameters of numeric type, or Equation commands that evaluate to scalar numeric values.

anArray(row, column) = value

If only one dimension is specified during assignment, row is assumed to be 1.

An Array can also be assigned as a whole in the Mission Sequence using another Array resource or an Equation that evaluates to an array. Both sides of the assignment must be identically-sized.

anArray = array expression

See Also: String, Variable

Fields

The Array resource has no fields; instead, the resource elements themselves are set to the desired values.

FieldDescription
rows

The number of rows (during creation), or the row being addressed. The total size of the array is rows × columns. This field is required.

Data Type

Integer

Allowed Values

1 ≤ rows ≤ 1000

Access

set

Default Value

1

Units

N/A

Interfaces

GUI, script

columns

The number of columns (during creation), or the column being addressed. The total size of the array is rows × columns. This field is required.

Data Type

Integer

Allowed Values

1 ≤ columns ≤ 1000

Access

set

Default Value

1

Units

N/A

Interfaces

GUI, script

value

The value of the array element being addressed.

Data Type

Real number

Allowed Values

-∞ < value < ∞

Access

set, get

Default Value

0.0

Units

N/A

Interfaces

GUI, script

GUI

The GMAT GUI lets you create multiple Array resources at once without leaving the window. To create an Array:

  1. In the Array Name box, type the desired name of the array.

  2. In the Row and Column boxes, type the desired number of rows and columns, respectively. To create a one-dimensional array, set Row to 1.

  3. Click the => button to create the array and add it to the list on the right.

  4. Click the Edit button to edit the array element values.

You can create multiple Array resources this way. To edit an existing array in this window, click it in the list on the right. Click Edit to change the element values, or edit the Row and Column values. You must click the => button again to save changes to the size of the array.

You can edit the elements of an Array by either clicking Edit while creating an array, or by double-clicking the array in the resources tree in the main GMAT window. The edit window allows you to change array elements individually using the row and column lists and clicking Update, or by directly entering data in the table in the lower portion of the window. The data table recognizes a few different mouse and keyboard controls:

  • Click a cell once to select it

  • Click a selected cell again, double-click an unselected cell, or press F2 to edit the value

  • Use the arrow keys to select adjacent cells

  • Click the corner header cell to select the entire table

  • Drag the column and row separators to adjust the row height or column width

  • Double-click the row or column separators in the heading to auto-size the row height or column width

Remarks

GMAT Array resources store an arbitrary number of numeric values organized into one or two dimensions, up to a maximum of 1000 elements per dimension. Internally, the elements are stored as double-precision real numbers, regardless of whether or not fractional portions are present. Array resources can be created and assigned using one or two dimension specifiers. This example shows the behavior in each case:

% a is a row vector with 3 elements
Create Array a[3]
a(1) = 1    % same as a(1, 1) = 1
a(2) = 2    % same as a(1, 2) = 2
a(3) = 3    % same as a(1, 3) = 3

% b is a matrix with 5 rows and 3 columns
Create Array b[5, 3]
b(1) = 1    % same as b(1, 1) = 1
b(2) = 2    % same as b(1, 2) = 2
b(3) = 3    % same as b(1, 3) = 3
b(4) = 4    % error: b(1, 4) does not exist
b(4, 3) = 4 % row 4, column 3

Examples

Creating and reporting an array:

Create ReportFile aReport
Create Variable i idx1 idx2
Create Array fib[9]

BeginMissionSequence

fib(1) = 0
fib(2) = 1
For i=3:9
   idx1 = i-1
   idx2 = i-2
   fib(i) = fib(idx1) + fib(idx2)
EndFor
Report aReport fib

Barycenter

Barycenter — The center of mass of selected celestial bodies

Description

A Barycenter is the center of mass of a set of celestial bodies. GMAT contains two barycenter resources: a built-in SolarSystemBarycenter resource and the Barycenter resource that allows you to build a custom Barycenter such as the Earth-Moon barycenter. This resource cannot be modified in the Mission Sequence.

See Also: LibrationPoint, CoordinateSystem, CelestialBody, SolarSystem

Options

OptionDescription
BodyNames

The list of CelestialBody resources included in the Barycenter.

Data Type

String array

Allowed Values

array of celestial bodies. You cannot add bodies to the built-in SolarySystemBarycenter resource. A CelestialBody can only appear once in the BodyNames list.

Access

set

Default Value

Earth, Luna

Units

N/A

Interfaces

GUI, script

GUI

The Barycenter dialog box allows you to define the celestial bodies included in a custom Barycenter. All celestial bodies, including user-defined bodies, are available for use in a Barycenter and appear in either the Available Bodies list or the Selected Bodies list. The example above illustrates the default configuration which contains Earth and Luna.

The SolarySystemBarycenter dialog box shown above is a built-in object and you cannot modify its configuration. See the Remarks section for details regarding the model for the SolarSystemBarycenter.

Remarks

Built-in SolarSystemBarycenter Object

The built-in SolarSystemBarycenter is modelled using the ephemerides selected in the SolarySystem.EphemerisSource field. For example, if you select DE421 for SolarSystem.EphemerisSource, then the barycenter location is computed by calling the DE421 ephemeris routines. For DE and SPICE ephemerides, the model for the solar system barycenter includes the planets and several hundred minor planets and asteroids. Note that you cannot add bodies to the SolarSystemBarycenter.

Custom Barycenter Objects

You can create a custom barycenter using the Barycenter resource. The position and velocity of a Barycenter is a mass-weighted average of the position and velocity of the included celestial bodies. In the equations below mi, ri, and vi are respectively the mass, position, and velocity of the ith body in the barycenter, and rb and vb are respectively the position and velocity of the barycenter.

Examples

Define the state of a spacecraft in SolarSystemBarycenter coordinates.

Create CoordinateSystem SSB
SSB.Origin = SolarSystemBarycenter
SSB.Axes   = MJ2000Eq

Create ReportFile aReport

Create Spacecraft aSpacecraft
aSpacecraft.CoordinateSystem = SSB
aSpacecraft.X  = -27560491.88656896
aSpacecraft.Y  = 132361266.8009069
aSpacecraft.Z  = 57419875.95483227
aSpacecraft.VX = -29.78491261798486
aSpacecraft.VY = 2.320067257851091
aSpacecraft.VZ = -1.180722388963864

BeginMissionSequence

Report aReport aSpacecraft.EarthMJ2000Eq.X aSpacecraft.EarthMJ2000Eq.Y ...                
             aSpacecraft.EarthMJ2000Eq.Z 

Report the state of a spacecraft in SolarSystemBarycenter coordinates.

Create CoordinateSystem SSB
SSB.Origin = SolarSystemBarycenter
SSB.Axes   = MJ2000Eq

Create Spacecraft aSpacecraft
Create ReportFile aReport

BeginMissionSequence

Report aReport aSpacecraft.SSB.X aSpacecraft.SSB.Y aSpacecraft.SSB.Z ...
      aSpacecraft.SSB.VX aSpacecraft.SSB.VY aSpacecraft.SSB.VZ

Create an Earth-Moon Barycenter and use it in a Sun-Earth-Moon LibrationPoint.

Create Barycenter EarthMoonBary
EarthMoonBary.BodyNames = {Earth,Luna}

Create LibrationPoint SunEarthMoonL2
SunEarthMoonL2.Primary   = Sun
SunEarthMoonL2.Secondary = EarthMoonBary
SunEarthMoonL2.Point     = L2

Create CoordinateSystem SEML2Coordinates
SEML2Coordinates.Origin = SunEarthMoonL2
SEML2Coordinates.Axes   = MJ2000Eq

Create Spacecraft aSpacecraft
GMAT aSpacecraft.DateFormat = UTCGregorian
GMAT aSpacecraft.Epoch = '09 Dec 2005 13:00:00.000'
GMAT aSpacecraft.CoordinateSystem = SEML2Coordinates
GMAT aSpacecraft.X  = -32197.88223741966
GMAT aSpacecraft.Y  = 211529.1500044117
GMAT aSpacecraft.Z  = 44708.57017366499
GMAT aSpacecraft.VX = 0.03209516489451751
GMAT aSpacecraft.VY = 0.06086386504053736
GMAT aSpacecraft.VZ = 0.0550442738917212

Create ReportFile aReport

BeginMissionSequence

Report aReport aSpacecraft.EarthMJ2000Eq.X aSpacecraft.EarthMJ2000Eq.Y ...                
             aSpacecraft.EarthMJ2000Eq.Z 

CelestialBody

CelestialBody — A celestial body model

Description

The CelestialBody resource is a model of a celestial body containing settings for the physical properties, as well as the models for the orbital motion and orientation. GMAT contains built-in models for the Sun, the 8 planets, Earth's moon, and Pluto. You can create a custom CelestialBody resource to model a planet, asteroid, comet, or moon. This resource cannot be modified in the Mission Sequence.

See Also: SolarSystem, Barycenter, LibrationPoint, CoordinateSystem

Fields

FieldDescription
CentralBody

The central body of the celestial body. The central body field is used primarily by the GUI.

Data Type

String

Allowed Values

Comet, Planet, Asteroid, or Moon

Access

set

Default Value

For Comet, Planet, Asteroid, the default is Sun. For Moon, the default is Earth.

Units

N/A

Interfaces

GUI, script

EquatorialRadius

The body's equatorial radius.

Data Type

Real

Allowed Values

Real > 0

Access

set

Default Value

6378.1363

Units

km

Interfaces

GUI, script

FileName

Path and/or name of texture map file used in OrbitView graphics.

Data Type

String

Allowed Values

A file of the following format:

.jpeg, .bmp, .png, .gif, .tif, .pcx, .pnm, .tga, or .xpm

Access

set

Default Value

'../data/graphics/texture/GenericCelestialBody.jpg'

Units

N/A

Interfaces

GUI, script

Flattening

The body's polar flattening.

Data Type

Real

Allowed Values

Real >= 0

Access

set

Default Value

0.0033527

Units

N/A

Interfaces

GUI, script

Mu

The body's gravitational parameter.

Data Type

Real

Allowed Values

Real > 0

Access

set

Default Value

398600.4415

Units

km^3/s^2

Interfaces

GUI, script

NAIFId

NAIF Integer ID for body.

Data Type

Integer

Allowed Values

Integer

Access

set

Default Value

-123456789

Units

N/A

Interfaces

GUI, script

NutationUpdateInterval

The time interval between updates for Earth nutation matrix. If NutationUpdateInterval = 3600, then GMAT only updates nutation on an hourly basis.

Data Type

Real

Allowed Values

Real >= 0

Access

set

Default Value

60

Units

sec.

Interfaces

GUI, script

OrbitSpiceKernelName

List of SPK kernels.

Data Type

Reference array

Allowed Values

valid array of SPK kernels

Access

set

Default Value

N/A

Units

N/A

Interfaces

GUI, script

OrientationEpoch

The reference epoch for orientation data.

Data Type

String

Allowed Values

6116.0 <= Epoch <= 58127.5

Access

set

Default Value

21545.0

Units

A1 Modified Julian Epoch

Interfaces

GUI, script

PosVelSource

The model for user-defined body orbit ephemeredes. GMAT currently only supports a single ephemeris model for custom bodies (SPICE) and this is set using PosVelSource field. The default for PosVelSource is SPICE and it is not necessary to configure this field in the current version of GMAT. This field has no effect for built-in bodies.

Data Type

String

Allowed Values

SPICE

Access

set

Default Value

DE405 for build in bodies. SPICE for user defined bodies.

Units

N/A

Interfaces

GUI, script

RotationConstant

The body's spin angle at the orientation epoch.

Data Type

Real

Allowed Values

Real

Access

set

Default Value

190.147

Units

deg

Interfaces

GUI, script

RotationDataSource

For Earth default is FK5IAU1980, for Luna default is DE405, for selected built in bodies IAU2000, and for selected built in bodies and all user defined bodies, default is IAUSimplified.

Data Type

String

Allowed Values

IAUSimplified, DE405, FK5IAU1980, IAU2000. See discussion below for more details as not all options are allowed for all bodies.

Access

set

Default Value

For Earth default is FK5IAU1980, for Luna default is DE405, for selected built in bodies IAU2000, and for selected built in bodies and all user defined bodies, default is IAUSimplified.

Units

N/A

Interfaces

GUI, script

RotationRate

The body's spin rate.

Data Type

Real

Allowed Values

Real

Access

set

Default Value

360.9856235

Units

deg/day

Interfaces

GUI, script

SpinAxisDECConstant

The declination of the body's spin axis at the orientation epoch.

Data Type

Real

Allowed Values

Real

Access

set

Default Value

90

Units

deg

Interfaces

GUI, script

SpinAxisDECRate

The rate of change of the body's spin axis declination.

Data Type

Real

Allowed Values

Real

Access

set

Default Value

-0.5570

Units

deg/century

Interfaces

GUI, script

SpinAxisRAConstant

The right ascension of the body's spin axis at the orientation epoch.

Data Type

Real

Allowed Values

Real

Access

set

Default Value

-0.641

Units

deg

Interfaces

GUI, script

SpinAxisRARate

The rate of change of the body's right ascension.

Data Type

Real

Allowed Values

Real

Access

set

Default Value

-0.641

Units

deg/century

Interfaces

GUI, script

GUI

The CelestialBody GUI has three tabs that allow you to set the physical properties, orbital properties, and the orientation model. CelestialBody resources can be used in ForceModels, CoordinateSystems, LibrationPoints, and Barycenters, among others. For a built-in CelestialBody, the Orbit and Orientation tabs are largely inactive and the behavior is discussed below. To create a custom Asteroid - as an example of how to create a custom CelestialBody - perform the following steps.

  1. In the Resource Tree, expand the SolarSystem folder.

  2. Right-click Sun and select Add -> Asteroid.

  3. In the New Asteroid dialog box, type the desired name.

The CelestialBody Properties tab is shown below. GMAT models all bodies as spherical ellipsoids and you can set the Equatorial Radius, Flattening, and Mu (gravitational parameter) on this dialog box, as well as the texture map used in OrbitView graphics displays.

The CelestialBody Orbit tab is shown below for creating a custom CelestialBody. Settings on this panel are inactive for built-in celestial bodies and the ephemeris for built-in bodies is configured on the SolarSystem dialog. The CentralBody field is populated automatically when the object is created and is always inactive. To configure SPICE ephemerides for a custom body, provide a list of SPK files and the NAIF ID. See the discussion below for more information on configuring SPICE files.

The CelestialBody Orientation tab is shown below. Most settings on this panel are inactive for built-in celestial bodies and exceptions for the Earth and Earth's moon are described further below. To define the orientation for a celestial body you provide a reference epoch, the initial orientation at the reference epoch, and angular rates. See the discussion below for a more detailed description of the orientation model.

The Earth and Earth's moon have unique fields to configure their orientation models. The Earth has an extra field called NutationUpdateInterval that can be used when lower fidelity, higher performance simulations are required.

Remarks

Celestial Body Orientation Model

The orientation of built-in celestial bodies is modeled using high fidelity theories on a per-body basis. The orientation of Earth is modeled using IAU-1976/FK5. The orientation of the Moon is modeled using lunar librations from the DE405 file. The remaining built-in celestial body orientations are modeled using data published by the IAU/IAG in "Report of the IAU/IAG Working Group on Cartographic Coordinates and Rotational Elements of the Planets and Satellites: 2000".

The orientation of a custom CelestialBody is modeled by providing three angles and their rates based on IAU/IAG conventions. The figure below illustrates the angles. The angles αo, δo, and W, are respectively the SpinAxisRAConstant, SpinAxisDECConstant, and RotationConstant. The angular rates are respectively SpinAxisRARate, SpinAxisDECRate, and RotationRate. All angles are referenced to the X-Y plane of the ICRF axis system. The constant values SpinAxisRAConstant, SpinAxisDECConstant, and RotationConstant are defined to be the values at the epoch defined in OrientationEpoch.

Below is an example illustrating how to configure a CelestialBody according to the IAU 2006 recommended values for Vesta. Note the orientation epoch typically used by the IAU is 01 Jan 2000 12:00:00.00.000 TDB and this must be converted to A1ModJulian which can easily be performed using the Spacecraft Orbit dialog box.

Create Asteroid Vesta
Vesta.CentralBody         = Sun
%  Note that currently the only available
%  format for OrientationEpoch is A1ModJulian
Vesta.OrientationEpoch    = 21544.99962789878  
Vesta.SpinAxisRAConstant  = 301.9
Vesta.SpinAxisRARate      = 0.9
Vesta.SpinAxisDECConstant = 90.9
Vesta.SpinAxisDECRate     = 0.0
Vesta.RotationConstant    = 292.9
Vesta.RotationRate        = 1617.332776

Note: The orientation models available for Earth and Luna have additional fields for configuration. Earth has an additional field called NutationUpdateInterval that controls the update frequency for the Nutation matrix. For high fidelity applications, NutationUpdateInterval should be set to zero. The RotationDataSource field for Earth and Luna defines the theory used for the rotation of those bodies. Currently, only FK5IAU1980 and DE405 are available for Earth and Luna respectively and the field is displayed for information purposes only. Future versions of GMAT will support DE421 for Luna and IAU-2000A theory for Earth.

Configuring Orbit Ephemerides

The ephemerides for built-in celestial bodies is specified by the SolarSystem.EphemerisSource field and the same source is used for all built-in bodies. Ephemerides for a custom CelestialBody are provided by SPICE files. Archives of available SPICE files can be found at the JPL NAIF site and the Solar System Dynamics site . JPL provides utilities to create custom SPICE files in the event existing kernels don't satisfy requirements for your application. To create custom SPICE kernels, see the documentation provided by JPL. The list of NAIF Ids for celestial bodies is located here.

Note that the DE files model the barycenter of planetary systems. So for Jupiter, when using DE405 for example, you are modeling Jupiter's location as the barycenter of the Jovian system. SPICE kernels differentiate the barycenter of a planetary system from the location of the individual bodies. So when using SPICE to model Jupiter, you are modeling the location of Jupiter using Jupiter's center of mass.

To specify the SPICE kernels for a custom CelestialBody, use the NAIFId, CentralBody, and SourceFileName fields. GMAT is distributed with an SPK file for CERES which has NAIF ID 2000001. Here is how to configure a CelestialBody to use the CERES SPICE ephemeris data.

Create CelestialBody Ceres
Ceres.CentralBody = Sun
Ceres.SourceFilename = '../data/planetary_ephem/spk/ceres_1900_2100.bsp'

Note: GMAT currently only supports a single ephemeris model for custom bodies (SPICE) and this is set using PosVelSource field. The default for PosVelSource is SPICE and it is not necessary to configure this field in the current version of GMAT.

Warning

NIAF distributes SPICE kernels for many celestial bodies and each kernel is consistent with a particular primary ephemeris release such as DE421. For high precision analysis, it is important to ensure that the ephemerides used for a custom celestial body are consistent with the ephemeris source selection in the SolarSystem.EphemerisSource field. SPICE kernels are typically distributed with a ".cmt" file and in that file the line that contains the ephemeris model looks like this:

Planetary Ephemeris Number: DE-0421/LE-0421

Configuring Physical Properties

GMAT models all celestial bodies as spherical ellipsoids. To define the physical properties use the Flattening, EquatorialRadius, and Mu fields.

Examples

Configure a CelestialBody to model Saturn's moon Titan. Note you must obtain the SPICE kernel named "sat351.bsp" from here and place it in the directory identified in the script snippet below

Create Moon Titan
Titan.NAIFId               = 606
Titan.OrbitSpiceKernelName = {...
                    '../data/planetary_ephem/spk/DE421AllPlanets.bsp',...
                    '../data/planetary_ephem/spk/sat288.bsp'}
Titan.EquatorialRadius     = 2575
Titan.Flattening           = 0
Titan.Mu                   = 8978.5215
Titan.PosVelSource         = 'SPICE'
Titan.CentralBody          = 'Saturn'
Titan.RotationDataSource   = 'IAUSimplified'
Titan.OrientationEpoch     = 21545
Titan.SpinAxisRAConstant   = 36.41
Titan.SpinAxisRARate       = -0.036
Titan.SpinAxisDECConstant  = 83.94
Titan.SpinAxisDECRate      = -0.004
Titan.RotationConstant     = 189.64
Titan.RotationRate         = 22.5769768

CoordinateSystem

CoordinateSystem — An axis and origin pair

Description

A CoordinateSystem in GMAT is defined as an origin and an axis system. You can select the origin of a CoordinateSystem from various points such as a CelestialBody, Spacecraft, GroundStation, or LibrationPoint to name a few. GMAT supports numerous axis systems such as J2000 equator, J2000 ecliptic, ICRF, ITRF, Topocentric, and ObjectReferenced among others. CoordinateSystems are tightly integrated into GMAT to enable you to define, report, and visualize data in coordinate systems relevant to your application. This resource cannot be modified in the Mission Sequence.

See Also: Spacecraft, Calculation Parameters, OrbitView

Fields

FieldDescription
Axes

The axes of the CoordinateSystem.

Data Type

String

Allowed Values

MJ2000Eq, MJ2000Ec, ICRF, ITRF, MODEq, MODEc, TODEq, TODEc, MOEEq, MOEEc, TOEEq, TOEEc, ObjectReferenced, Equator, BodyFixed, BodyInertial, GSE, GSM, Topocentric, BodySpinSun

Access

set

Default Value

MJ2000Eq

Units

N/A

Interfaces

GUI, script

Epoch

The reference epoch for the CoordinateSystem. This field is only used for TOE amd MOE axis types.

Data Type

String

Allowed Values

A1 Modified Julian epoch.

Access

set

Default Value

21545

Units

Modified Julian Date

Interfaces

GUI, script

Origin

The origin of the CoordinateSystem.

Data Type

String

Allowed Values

CelestialBody, Spacecraft, LibrationPoint, Barycenter, SolarSystemBarycenter, GroundStation

Access

set

Default Value

Earth

Units

N/A

Interfaces

GUI, script

Primary

The primary body for an ObjectReferenced axis system. This field is only used if Axes = ObjectReferenced. See the discussion below for more information on how Primary and Secondary are used to compute ObjectReferenced axes.

Data Type

String

Allowed Values

CelestialBody, Spacecraft, LibrationPoint, Barycenter, SolarSystemBarycenter, GroundStation

Access

set

Default Value

Earth

Units

N/A

Interfaces

GUI, script

Secondary

The secondary body for an ObjectReferenced axis system. This field is only used if Axes = ObjectReferenced. See the discussion below for more information on how Primary and Secondary are used to compute ObjectReferenced axes.

Data Type

String

Allowed Values

CelestialBody, Spacecraft, LibrationPoint, Barycenter, SolarSystemBarycenter, GroundStation

Access

set

Default Value

Luna

Units

N/A

Interfaces

GUI, script

XAxis

The x-axis definition for an ObjectReferenced axis system. This field is only used if Axes = ObjectReferenced. See the discussion below for more information on how the axes are computed for ObjectReferenced axis systems.

Data Type

String

Allowed Values

R,V, N, -R, -V, -N, or empty

Access

set

Default Value

R

Units

N/A

Interfaces

GUI, script

YAxis

The y-axis definition for an ObjectReferenced axis system. This field is only used if Axes = ObjectReferenced. See the discussion below for more information on how the axes are computed for ObjectReferenced axis systems.

Data Type

String

Allowed Values

R,V, N, -R, -V,-N, or empty

Access

set

Default Value

No Default

Units

N/A

Interfaces

GUI, script

Zaxis

The z-axis for an ObjectReferenced axis system. This field is only used if Axes = ObjectReferenced. See the discussion below for more information on how the axes are computed for ObjectReferenced axis systems.

Data Type

String

Allowed Values

R,V, N, -R, -V,-N, or empty

Access

set

Default Value

N

Units

N/A

Interfaces

GUI, script

GUI

The New Coordinate System dialog box shown above appears when you add a new coordinate system in the Resource Tree. You provide a name for the new CoordinateSystem in the Coordinate System Name box and configure the CoordinateSystem by selecting the Origin and Axes types along with other settings. Some settings, such as Primary and Secondary, are only active for particular Axes types and those dependencies are described below.

When editing an existing CoordinateSystem, you use the CoordinateSystem dialog box. The default configuration is shown above.

If you select ObjectReferenced for the Axes type, then the Primary, Secondary, X, Y, and Z fields are activated. You can use the ObjectReferenced axis system to define coordinates based on the motion of two space objects such as Spacecraft, CelestialBodies, or Barycenters to name a few. See the discussion below for a detailed definition of the ObjectReferenced axis system.

If you select TOEEq, TOEEc, MOEEq, or MOEEc as the axis type, then the A1MJd Epoch field is activated. Use the A1MJd Epoch field to define the reference epoch of the coordinate system.

Remarks

Computation of J2000-Based Axes using IAU76/FK5 Reduction

FK5 reduction is the transformation that rotates a vector expressed in the MJ2000Eq system to the EarthFixed CoordinateSystem. There are many coordinate systems that are intermediate rotations in FK5 reduction and this section describes how the following axes types are computed: MJ2000Eq, MJ2000Ec, EarthFixed, MODEq, MODEc,TODEq,TODEc, MODEq, MODEc, TODEq, and TODEc axes systems.

The time varying orientation of the Earth is complex due to interactions between the Earth and its external environment (the Sun and Moon and Planets) and internal dynamics. The orientation cannot currently be modelled to the accuracy required by many space applications and FK5 reduction is a combination of dynamical modelling along with daily corrections from empirical observations. The figure below illustrates components of motion of the Earth with respect to inertial space. The primary components of the motion of the Earth with respect to inertial space are Precession, Nutation, Sidereal time and, Polar Motion.

The principal moment of inertia is defined as the Celestial Ephemeris Pole. Due to the fact that Earth’s mass distribution changes with time, the Celestial Ephemeris Pole is not constant with respect to the Earth’s surface. Precession is defined as the coning motion that the Celestial Ephemeris Pole makes around the ecliptic north pole. The other principal component of the motion of the Celestial Ephemeris Pole is called nutation and is the oscillation in the angle between the Celestial Ephemeris Pole and the north ecliptic pole. The theory of Precession and Nutation come from dynamical models of the Earth’s motion. The Sidereal time is the rotation of the Earth about the Celestial Ephemeris Pole. The sidereal time model is a combination of theory and observation. The Earth’s spin axis direction is not constant with respect to the Earth’s crust and its motion is called Polar Motion. A portion of polar motion is due to complicated dynamics, and a portion is due to unmodelled errors in nutation. Polar motion is determined from observation.

The True of Date (TOD) systems and Mean of Date (MOD) systems are intermediate coordinate systems in FK5 reduction and are commonly used in analysis. The details of the computations are contained in the GMAT mathematical specification and the figure below is included here for summary purposes. The following abbreviations are used in the figure. PM: Polar Motion, ST: Sideral Time, NUT: Nutation, PREC: Precession, ITRF: International Terrestrial Reference Frame (Earth Fixed), PEF: Pseudo Earth Fixed, TODEq: True of Date Equator, TODEc: True of Date Ecliptic, MODEc: Mean of Date Ecliptic, MODEq: Mean of Date Equator, FK5: J2000 Equatorial Inertial (IAU-1976/1980).

Computation of ICRF and ITRF Axes using IAU2000 Conventions

The computation for the International Celestial Reference Frame (ICRF) and the International Terestrial Reference Fame (ITRF) are computed using the IAU 2000A theory with the 2006 update to precession. GMAT uses the Celestial Intermediate Origin (CIO) method of transformation which avoids issues associated with precession and nutation. In the CIO model, the Celestial Intermediate Pole unit vector is modeled using the variables X and S and the CIO locator, s. For performance reasons, GMAT interpolates X, Y, and s, from precomputed values stored in the file named ICRF_Table.txt distributed with GMAT.

GMAT models the rotation from ICRF to MJ200Eq by rotating through the EarthFixed frame which is identical for both the old (1976) and new (2000) theories. For performance reasons, the conversion from ICRF to MJ2000Eq is interplolated from pre-computed values of the Euler axis and angle between those frames. Note that GMAT does not currenty support the IAU2000 body fixed frame for Earth and that model will be included in a future release.

Computation of ObjectReference Axis System

An ObjectReferenced axis system is defined by the motion of one object with respect to another object. The figure below defines the six principal directions of an Object Referenced axis system. One is the relative position of the secondary object with respect to the primary object, denoted by r, expressed in the inertial frame. The second is the relative velocity, denoted here by v, of the secondary object with respect to the primary, expressed in the inertial frame. The third direction is the vector normal to the direction of motion which is denoted by n and is calculated using n = r × v. The remaining three directions are the negative of the first three yielding the complete set: {R,-R, V,-V, N,-N}.

You define an Object Referenced axis system by defining two axes from the three available [X, Y, and Z] using the six available options {R,-R, V,-V, N,-N}. Given two directions, GMAT constructs an orthogonal, right-handed CoordinateSystem. For example, if you choose the x-axis to be in the direction of R and the z-axis to be in the direction of N, GMAT completes the right-handed set by setting the y-axis in the direction of NxR. If you choose permutations that result in a non-orthogonal or left-handed CoordinateSystem, GMAT will throw an error message.

Warning

GMAT currently assumes that terms involving the cross and dot product of acceleration are zero when computing ObjectReferenced rotation matrices.

Overview of Built-in Coordinate Systems

NameOriginAxesDescription
EarthMJ2000EqEarthMJ2000Eq

An Earth equator inertial system based on IAU-1976/FK5 theory with 1980 update to nutation.

EarthMJ2000EcEarthMJ2000Ec

An Earth ecliptic inertial system based on IAU-1976/FK5 theory with 1980 update to nutation.

EarthFixedEarthBodyFixed

An Earth fixed system based on IAU-1976/FK5 theory with 1980 update to nutation.

EarthICRFEarthICRF

An Earth equator inertial system based on IAU-2000 theory with 2006 update to precession.

Description of Axes Types

Axes NameOrigin LimitationsBase TypeDescription
MJ2000EqNoneIAU-1976 FK5

An inertial coordinate system. The nominal x-axis points along the line formed by the intersection of the Earth’s mean equatorial plane and the mean ecliptic plane (at the J2000 epoch), in the direction of Aries. The z-axis is normal to the Earth’s mean equator at the J2000 epoch and the y-axis completes the right-handed system. The mean planes of the ecliptic and equator, at the J2000 epoch, are computed using IAU-1976/FK5 theory with 1980 update for nutation.

MJ2000EcNoneIAU-1976 FK5

An inertial coordinate system. The x-axis points along the line formed by the intersection of the Earth’s mean equator and the mean ecliptic plane at the J2000 epoch. The z-axis is normal to the mean equatorial plane at the J2000 Epoch and the y-axis completes the right-handed set. This system is computed using IAU-1976/FK5 theory with 1980 update for nutation.

ICRFNoneIAU-2000

An inertial coordinate system. The axes are close to the mean Earth equator and pole at the J2000 epoch, and at the Earth’s surface, the RSS difference between vectors expressed in MJ2000Eq and ICRF is less than 1 m. Note that since MJ2000Eq and ICRF are imperfect realizations of inertial systems, the transformation between them is time varying. This axis system is computed using IAU-2000A theory with 2006 update for precession.

MODEqNoneIAU-1976 FK5

A quasi-inertial coordinate system referenced to Earth’s mean equator at the current epoch. The current epoch is defined by the context of use and usually comes from the spacecraft or graphics epoch. This system is computed using IAU-1976/FK5 theory with 1980 update for nutation.

MODEcNoneIAU-1976 FK5

A quasi-inertial coordinate system referenced to the mean ecliptic at the current epoch. The current epoch is defined by the context of use and usually comes from the spacecraft or graphics epoch. This system is computed using IAU-1976/FK5 theory with 1980 update for nutation.

TODEqNoneIAU-1976 FK5

A quasi-inertial coordinate system referenced to Earth’s true equator at the current epoch. The current epoch is defined by the context of use and usually comes from the spacecraft or graphics epoch. This system is computed using IAU-1976/FK5 theory with 1980 update for nutation.

TODEcNoneIAU-1976 FK5

A quasi-inertial coordinate system referenced to Earth’s true ecliptic at the current epoch. The current epoch is defined by the context of use and usually comes from the spacecraft or graphics epoch. This system is computed using IAU-1976/FK5 theory with 1980 update for nutation.

MOEEqNoneIAU-1976 FK5

A quasi-inertial coordinate system referenced to Earth’s mean equator at the reference epoch. The reference epoch is defined on the CoordinateSystem object. This system is computed using IAU-1976/FK5 theory with 1980 update for nutation.

MOEEcNoneIAU-1976 FK5

A quasi-inertial coordinate system referenced to the mean ecliptic at the reference epoch. The reference epoch is defined on the CoordinateSystem object. This system is computed using IAU-1976/FK5 theory with 1980 update for nutation.

TOEEqNoneIAU-1976 FK5

A quasi-inertial coordinate system referenced to Earth’s true equator at the reference epoch. The reference epoch is defined on the CoordinateSystem object. This system is computed using IAU-1976/FK5 theory with 1980 update for nutation.

TOEEcNoneIAU-1976 FK5

A quasi-inertial coordinate system referenced to the true ecliptic at the reference epoch. The reference epoch is defined on the CoordinateSystem object. This system is computed using IAU-1976/FK5 theory with 1980 update for nutation.

ObjectReferencedNoneIAU-1976 FK5

An ObjectReferenced system is a CoordinateSystem whose axes are defined by the motion of one object with respect to another object. See the discussion above for a detailed description of the ObjectReferenced axis system.

EquatorCelestial BodyIAU-1976 FK5

A true of date equator axis system for the celestial body selected as the origin. The Equator system is defined by the body’s equatorial plane and its intersection with the ecliptic plane, at the current epoch. The current epoch is defined by the context of use and usually comes from the spacecraft or graphics epoch. The Equator system for Earth is computed using IAU-1976/FK5 theory. For the Moon, the Equator system is computed using the theory selected in the field Luna.RotationDataSource. For other built-in celestial bodies, the body fixed axes are computed using models provided by the IAU in “Report of the IAU/IAG Working Group on Cartographic Coordinates and Rotational Elements of the Planets and Satellites: 2000”.

BodyFixedCelestial BodyIAU-1976 FK5

The BodyFixed axis system is referenced to the body equator and the prime meridian of the body. The BodyFixed system for Earth is computed using IAU-1976/FK5 theory. For the Moon, the BodyFixed system is computed using the theory selected in the field Luna.RotationDataSource. For other built-in celestial bodies, the body fixed axes are computed using models provided by the IAU in “Report of the IAU/IAG Working Group on Cartographic Coordinates and Rotational Elements of the Planets and Satellites: 2000”.

BodyInertialCelestial BodyIAU-1976 FK5

An inertial system referenced to the equator ( at the J2000 epoch ) of the celestial body selected as the origin of the CoordinateSystem. Because the BodyInertial axis system uses different theories for different bodies, the following definitions describe only the nominal axis configurations. The x-axis points along the line formed by the intersection of the bodies equator and earth’s mean equator at J2000. The z-axis points along the body's spin axis direction at the J2000 epoch. The y-axis completes the right-handed set. For Earth, the BodyInertial axis system is identical to the MJ2000Eq system. For the Moon, the orientation at the J2000 epoch is computed using the theory selected in the field Luna.RotationDataSource. For all other built-in celestial bodies, the BodyInertial axis system is based upon the IAU report entitled “Report of the IAU/IAG Working Group on Cartographic Coordinates and Rotational Elements of the Planets and Satellites: 2000”

GSENoneIAU-1976 FK5

The Geocentric Solar Ecliptic system. The x-axis points from Earth to the Sun. The z-axis is defined as the cross product RxV where R and V are earth’s position and velocity with respect to the sun respectively. The y-axis completes the right-handed set. The GSE axes are computed using the relative motion of the Earth and Sun even if the origin is not Earth.

GSMNoneIAU-1976 FK5

The Geocentric Solar Magnetic system. The x-axis points from Earth to the Sun. The z-axis is defined to be orthogonal to the x-axis and lies in the plane of the x-axis and Earth’s magnetic dipole vector. The y-axis completes the right-handed set. The GSM axes are computed using the relative motion of the Earth and Sun even if the origin is not Earth.

TopocentricEarthIAU-1976 FK5

A GroundStation-based coordinate system. The y-axis points due East and the z-axis is normal to the local horizon. The x-axis completes the right handed set.

BodySpinSunCelestial BodyIAU-1976 FK5

A celestial body spin-axis-referenced system. The x-axis points from the celestial body to the Sun. The y-axis is computed as the cross product of the x-axis and the body's spin axis. The z-axis completes the right-handed set.

Examples

Define a Spacecraft’s state in EarthFixed coordinates.

Create Spacecraft aSpacecraft
aSpacecraft.CoordinateSystem = EarthFixed
aSpacecraft.X = 7100
aSpacecraft.Y = 0
aSpacecraft.Z = 1300
aSpacecraft.VX = 0
aSpacecraft.VY = 7.35
aSpacecraft.VZ = 1

Report a Spacecraft’s state in GroundStation Topocentric coordinates.

Create Spacecraft aSat
Create Propagator aProp
Create GroundStation aStation

Create CoordinateSystem stationTopo
stationTopo.Origin = aStation
stationTopo.Axes   = Topocentric

Create ReportFile aReport
aReport.Filename = 'ReportFile1.txt'
aReport.Add = {aSat.stationTopo.X aSat.stationTopo.Y aSat.stationTopo.Z ... 
               aSat.stationTopo.VX aSat.stationTopo.VY aSat.stationTopo.VZ}

BeginMissionSequence

Propagate aProp(aSat) {aSat.ElapsedSecs = 8640.0}

View a trajectory in an ObjectReferenced, rotating-LibrationPoint system.

%  Create the Earth-Moon Barycenter and Libration Point
Create Barycenter EarthMoonBary
EarthMoonBary.BodyNames = {Earth,Luna};

Create LibrationPoint SunEarthMoonL1
SunEarthMoonL1.Primary   = Sun;
SunEarthMoonL1.Secondary = EarthMoonBary
SunEarthMoonL1.Point     = L1;

%  Create the coordinate system
Create CoordinateSystem RotatingSEML1Coord
RotatingSEML1Coord.Origin    = SunEarthMoonL1
RotatingSEML1Coord.Axes      = ObjectReferenced
RotatingSEML1Coord.XAxis     = R
RotatingSEML1Coord.ZAxis     = N
RotatingSEML1Coord.Primary   = Sun
RotatingSEML1Coord.Secondary = EarthMoonBary

%  Create the spacecraft and propagator
Create Spacecraft aSpacecraft
aSpacecraft.DateFormat       = UTCGregorian
aSpacecraft.Epoch            = '09 Dec 2005 13:00:00.000'
aSpacecraft.CoordinateSystem = RotatingSEML1Coord
aSpacecraft.X  = -32197.88223741966
aSpacecraft.Y  = 211529.1500044117
aSpacecraft.Z  = 44708.57017366499
aSpacecraft.VX = 0.03209516489451751
aSpacecraft.VY = 0.06100386504053736
aSpacecraft.VZ = 0.0550442738917212

Create Propagator aPropagator
aPropagator.FM           = aForceModel
aPropagator.MaxStep = 86400
Create ForceModel aForceModel
aForceModel.PointMasses = {Earth,Sun,Luna}

% Create a 3-D graphic
Create OrbitView anOrbitView
anOrbitView.Add                  = {aSpacecraft,  Earth, Sun, Luna}
anOrbitView.CoordinateSystem     = RotatingSEML1Coord
anOrbitView.ViewPointReference   = SunEarthMoonL1
anOrbitView.ViewPointVector      = [-1500000 0 0 ]
anOrbitView.ViewDirection        = SunEarthMoonL1
anOrbitView.ViewUpCoordinateSystem = RotatingSEML1Coord
anOrbitView.Axes                 = Off
anOrbitView.XYPlane              = Off

BeginMissionSequence

Propagate aPropagator(aSpacecraft, {aSpacecraft.ElapsedDays = 180})

DifferentialCorrector

DifferentialCorrector — A numerical solver

Description

A DifferentialCorrector (DC) is a numerical solver for solving boundary value problems. It is used to refine a set of variable parameters in order to meet a set of goals defined for the modeled mission. The DC in GMAT uses a simple shooting method where the derivatives are determined using finite differencing. In the mission sequence, you use the DifferentialCorrector resource in a Target control sequence to solve the boundary value problem. In GMAT, differential correctors are often used to determine the maneuver components required to achieve desired orbital conditions, say, B-plane conditions at a planetary flyby.

You must create and configure a DifferentialCorrector resource for your application by setting numerical properties of the solver such as the maximum number of allowed iterations and choice of derivative method used to calculate the finite differences. You can also select among different output options that show increasing levels of information for each differential corrector iteration.

This resource cannot be modified in the Mission Sequence.

See Also: Target, Vary, Achieve

Fields

FieldDescription
DerivativeMethod

Chooses between one-sided and central differencing for numerically determining the derivative.

Data Type

String

Allowed Values

ForwardDifference, BackwardDifference, CentralDifference

Access

set

Default Value

ForwardDifference

Units

N/A

Interfaces

GUI, script

MaximumIterations

Sets the maximum number of nominal passes the DifferentialCorrector is allowed to take during the attempt to find a solution. If the maximum iterations is reached, GMAT exits the target loop and continues to the next command in the mission sequence. In this case, the objects retain their states as of the last nominal pass through the targeting loop.

Data Type

Integer

Allowed Values

Integer >= 1

Access

set

Default Value

25

Units

N/A

Interfaces

GUI, script

ReportFile

Specifies the path and file name for the DifferentialCorrector report.  The report is only generated if ShowProgress is set to true. 

Data Type

String

Allowed Values

Filename consistent with OS

Access

set

Default Value

DifferentialCorrectorDCName.data, where DCname is the name of the DifferentialCorrector

Units

N/A

Interfaces

GUI, script

ReportStyle

Controls the amount and type of information written to the file defined in the ReportFile field. Currently, the Normal and Concise options contain the same information: the Jacobian, the inverse of the Jacobian, the current values of the control variables, and achieved and desired values of the constraints. Verbose contains values of the perturbation variables in addition to the data for Normal and Concise. Debug contains detailed script snippets at each iteration for objects that have control variables.

Data Type

String

Allowed Values

Normal, Concise, Verbose, Debug

Access

set

Default Value

Normal

Units

N/A

Interfaces

GUI, script

ShowProgress

When the ShowProgress field is set to true, then data illustrating the progress of the differential correction process are written to the message window and the ReportFile. The message window is updated with information on the current control variable values and the contraint variances.  When the ShowProgress field is set to false, no information on the progress of the differential correction process is displayed to the message window or written to the ReportFile.

Data Type

String

Allowed Values

true, false

Access

set

Default Value

true

Units

N/A

Interfaces

GUI, script

GUI

The DifferentialCorrector dialog box allows you to specify properties of a DifferentialCorrector such as maximum iterations, choice of derivative method used to calculate the finite differences, and choice of reporting options.

To create a DifferentialCorrector resource, navigate to the Resources tree, expand the Solvers folder, right-click on the Boundary Value Solvers folder, point to Add, and click DifferentialCorrector. A resource named DC1 will be created. Double-click on the DC1 resource to bring up the following Differential Corrector dialog box.

Remarks

Resource and Command Interactions

The DifferentialCorrector object can only be used in the context of targeting-type commands. Please see the documentation for Target, Vary, and Achieve for more information and worked examples.

Examples

Create a DifferentialCorrector object.

Create DifferentialCorrector DC1
DC1.ShowProgress = true
DC1.ReportStyle = Normal
DC1.ReportFile = 'DifferentialCorrectorDC1.data'
DC1.MaximumIterations = 25
DC1.DerivativeMethod = ForwardDifference

BeginMissionSequence    

To see how the DifferentialCorrector object is used in conjunction with Target, Vary, and Achieve commands to solve orbit problems, see the Target command examples.


EphemerisFile

EphemerisFile — Generate spacecraft’s ephemeris data

Description

EphemerisFile is a user-defined resource that generates spacecraft’s ephemeris data in a report format. You can generate spacecraft’s ephemeris data in any of the user-defined coordinate frames. GMAT allows you to output ephemeris data in either CCSDS or SPK file formats. See the Remarks section for more details. EphemerisFile resource can be configured to generate ephemeris data at default integration steps or by entering user-selected step sizes.

GMAT allows you to generate any number of ephemeris data files by creating multiple EphermisFile resources. Spacecraft’s ephemeris data is always provided in UTC epoch format. An EphemerisFile resource can be created using either the GUI or script interface. GMAT also provides the option of when to write and stop writing ephemeris data to a text file through the Toggle On/Off commands. See the Remarks section below for detailed discussion of the interaction between EphemerisFile resource and Toggle command.

See Also: CoordinateSystem, Toggle

Fields

FieldDescription
InterpolationOrder

Allows you to set the interpolation order for the available interpolator methods (Lagrange or Hermite) for either CCSDS-OEM or SPK file formats. This field cannot be modified in the Mission Sequence.

Data Type

Integer

Allowed Values

1 <= Integer Number <= 10

Access

Set

Default Value

7

Units

N/A

Interfaces

GUI, script

StepSize

The ephemeris file is generated at the step size that is specified for StepSize field. The user can generate ephemeris file at default Integration step size (using raw integrator steps) or by defining a fixed step size provided by user. This field cannot be modified in the Mission Sequence.

Data Type

Real

Allowed Values

Real Number > 0.0 or equals Default Value

Access

Set

Default Value

IntegratorSteps

Units

N/A

Interfaces

GUI, script

EpochFormat

Allows you to select format of the epoch that the user defines in InitialEpoch and FinalEpoch fields. This field cannot be modified in the Mission Sequence.

Data Type

Enumeration

Allowed Values

UTCGregorian, UTCModJulian, TAIGregorian, TAIModJulian, TTGregorian, TTModJulian, A1Gregorian, A1ModJulian

Access

Set

Default Value

UTCGregorian

Units

N/A

Interfaces

GUI, script

FileFormat

Allows the user to generate ephemeris file in two available file formats: CCSDS-OEM or SPK. This field cannot be modified in the Mission Sequence.

Data Type

Enumeration

Allowed Values

CCSDS-OEM, SPK

Access

Set

Default Value

CCSDS-OEM

Units

N/A

Interfaces

GUI, script

FileName

Allows the user to name the generated ephemeris file and save it in user-specified location. This field cannot be modified in the Mission Sequence.

Data Type

String

Allowed Values

Valid File Path and Name

Access

set

Default Value

EphemerisFile1.eph

Units

N/A

Interfaces

GUI, script

FinalEpoch

Allows the user to specify the time span of an ephemeris file. Ephemeris file is generated up to final epoch that is specified in FinalEpoch field. This field cannot be modified in the Mission Sequence.

Data Type

String

Allowed Values

user-defined final epoch or Default Value

Access

set

Default Value

FinalSpacecraftEpoch

Units

N/A

Interfaces

GUI, script

InitialEpoch

Allows the user to specify the starting epoch of the ephemeris file. Ephemeris file is generated starting from the epoch that is defined in InitialEpoch field. This field cannot be modified in the Mission Sequence.

Data Type

String

Allowed Values

user-defined initial epoch or Default Value

Access

set

Default Value

InitialSpacecraftEpoch

Units

N/A

Interfaces

GUI, script

Interpolator

This field defines the available interpolator method that was used to generate ephemeris file. Available Interpolators are Lagrange or Hermite. This field cannot be modified in the Mission Sequence.

Data Type

String

Allowed Values

Lagrange for CCSDS file, Hermite for SPK file

Access

set

Default Value

Lagrange

Units

N/A

Interfaces

GUI, script

WriteEphemeris

Allows the user to optionally calculate/write or not calculate/write an ephemeris that has been created and configured. This field cannot be modified in the Mission Sequence.

Data Type

Boolean

Allowed Values

true,false

Access

set

Default Value

true

Units

Unit

Interfaces

GUI, script

CoordinateSystem

Allows the user to generate ephemeris data in the coordinate system that is selected from CoordinateSystem field. The user can choose to also generate ephemeris data in user-defined coordinate system. This field cannot be modified in the Mission Sequence.

Data Type

String

Allowed Values

CoordinateSystem resource

Access

set, get

Default Value

EarthMJ2000Eq

Units

N/A

Interfaces

GUI, script

Spacecraft

Allows the user to generate ephemeris data of spacecraft(s) that are defined in Spacecraft field. This field cannot be modified in the Mission Sequence.

Data Type

String

Allowed Values

Default spacecraft or any number of user-defined spacecrafts or formations

Access

set, get

Default Value

DefaultSC

Units

N/A

Interfaces

GUI, script

UpperLeft

Allows the user to pan the generated ephemeris file display window in any direction. First value in [0 0] matrix helps to pan the window horizontally and second value helps to pan the window vertically. This field cannot be modified in the Mission Sequence.

Data Type

Real array

Allowed Values

Any Real number

Access

set

Default Value

[ 0 0 ]

Units

N/A

Interfaces

script

Size

Allows the user to control the display size of generated ephemeris file panel. First value in [0 0] matrix controls horizonal size and second value controls vertical size of ephemeris file display window. This field cannot be modified in the Mission Sequence.

Data Type

Real array

Allowed Values

Any Real number

Access

set

Default Value

[ 0 0 ]

Units

N/A

Interfaces

script

RelativeZOrder

Allows the user to select which generated ephemeris file display window is to displayed first on the screen. The EphemerisFile resource with lowest RelativeZOrder value will be displayed last while EphemerisFile resource with highest RelativeZOrder value will be displayed first. This field cannot be modified in the Mission Sequence.

Data Type

Integer

Allowed Values

Integer ≥ 0

Access

set

Default Value

0

Units

N/A

Interfaces

script

Maximized

Allows the user to maximize the generated ephemeris file window. This field cannot be modified in the Mission Sequence.

Data Type

Boolean

Allowed Values

true,false

Access

set

Default Value

false

Units

N/A

Interfaces

script

GUI

The figure below shows the default settings for the EphemerisFile resource:

GMAT allows you to modify InitialEpoch, FinalEpoch and StepSize fields of EphemerisFile resource. Instead of always generating the ephemeris file at default time span settings of InitialSpacecraftEpoch and FinalSpacecraftEpoch, you can define your own initial and final epochs. Similarly, instead of using the default IntegratorSteps setting for StepSize field, you can generate the ephemeris file at the step size of your choice.

The GUI figure below shows ephemeris file which will be generated from initial epoch of 01 Jan 2000 14:00:00.000 to final epoch of 01 Jan 2000 20:00:00.000 while using non-default step size of 300 seconds:

Remarks

Behavior of Coordinate System Field for CCSDS File Format

If the selected CoordinateSystem uses MJ2000Eq axes, the CCSDS ephemeris file contains “EME2000” for the REF_FRAME according to CCSDS convention. By CCSDS requirements, non-standard axes names are allowed when documented in an ICD. The CoordinateSystems specifications document in the user's guide is the ICD for all axes supported by GMAT. Also if you create a new coordinate system whose origin is Luna, then the CCSDS ephemeris file contains “Moon” for the CENTER_NAME.

There is one important difference between GMAT and IAU conventions. By IAU convention, there is no name for the IAU2000 axes that is independent of the origin. GCRF is coordinate system centered at earth with IAU2000 axes, and ICRF is a coordinate system centered at the solar system barycenter with IAU2000 axes. We have chosen to name the IAU2000 axes ICRF regardless of the origin. Please refer to CoordinateSystems specifications document to read more about built-in coordinate systems and description of Axes types that GMAT supports.

Behavior of Ephemeris File during Discontinuous & Iterative Processes

When generating an ephemeris file for a mission sequence, GMAT separately interpolates ephemeris segments that are bounded by discontinuous or discrete mission events. Discontinuous or discrete mission sequence events can range from impulsive or finite-burn maneuvers, changes in dynamics models or when using assignment commands. Furthermore, when a mission sequence employs iterative processes such as differential correction or optimization, GMAT only writes the ephemeris for the final solution from the iterative processes. See the Examples section below to see how an ephemeris file is generated during a discontinuous event such as an impulsive burn and iterative process like differential correction.

Version 1 of CCSDS Orbit Data Messages (ODMs) document used to require that the ephemeris be generated in increasing time order and only going forward. However version 2 of CCSDS ODM document now allows for ephemeris file to be generated backwards as well. Currently in GMAT, when you propagate a spacecraft backwards in time, then the ephemeris is also generated backwards.

Behavior of Ephemeris File When It Does Not Meet CCSDS File Format Requirements

When an ephemeris file is generated, it needs to follow the Recommended Standard for ODMs that has been prepared by the CCSDS. The set of orbit data messages described in the Recommended Standard is the baseline concept of trajectory representation in data interchange applications that are cross-supported between Agencies of the CCSDS. CCSDS-ODM Recommended Standard documents establishes a common framework and provides a common basis for the interchange of orbit data.

Currently, the ephemeris file that is generated by GMAT meets most of the recommended standards that are prescribed by the CCSDS. However whenever there is a case when GMAT’s ephemeris violates CCSDS file format requirements, then the generated ephemeris file will display a warning in ephemeris file’s Header section. More specifically, this warning will be given under COMMENT and it will let you know that this ephemeris file does not fully satisfy CCSDS file formatting requirements.

Behavior of Interpolation Order Field for CCSDS and SPK File Formats

For CCSDS file formats, whenever there is not enough raw data available to support the requested interpolation type and order, GMA throws an error message and stops interpolation. GMAT still generates the ephemeris file but no spacecraft ephemeris data is written to the file and only the file’s Header section will be there. Within the Header section and under COMMENT, a message will be thrown saying that not enough raw data is available to generate spacecraft ephemeris data at the requested interpolation order.

For SPK file formats, raw data is always collected at every integrator step for each segment and then sent to SPK kernel writer. No interpolation takes place for SPK ephemeris file.

Behavior When Using EphemerisFile Resource & Toggle Command

EphemerisFile resource generates ephemeris file at each propagation step of the entire mission duration. If you want to generate ephemeris data during specific points in your mission, then a Toggle On/Off command can be inserted into the Mission tree to control when the EphemerisFile resource writes data. When Toggle Off command is issued for an EphemerisFile subscriber, no data is sent to a file until a Toggle On command is issued. Similarly, when a Toggle On command is used, ephemeris data is sent to a file at each integration step until a Toggle Off command is used.

Below is an example script snippet that shows how to use Toggle Off/On commands while using the EphemerisFile resource. No ephemeris data is sent for first two days of propagation and only the data that is collected during last four days of propagation is sent to text file called ‘EphemerisFile1.eph’:

Create Spacecraft aSat
Create Propagator aProp

Create EphemerisFile anEphmerisFile

anEphmerisFile.Spacecraft = aSat
anEphmerisFile.Filename = 'EphemerisFile1.eph'

BeginMissionSequence

Toggle anEphmerisFile Off
Propagate aProp(aSat) {aSat.ElapsedDays = 2}
Toggle anEphmerisFile On
Propagate aProp(aSat) {aSat.ElapsedDays = 4}

Examples

This example shows how to generate a simple ephemeris file. Ephemeris file is generated for two days of propagation. At default settings, ephemeris file is generated at each integrator step and in CCSDS file format. Ephemeris data is sent to text file called ‘EphemerisFile2.eph’:

Create Spacecraft aSat
Create Propagator aProp

Create EphemerisFile anEphmerisFile

anEphmerisFile.Spacecraft = aSat
anEphmerisFile.Filename = 'EphemerisFile2.eph'

BeginMissionSequence

Propagate aProp(aSat) {aSat.ElapsedDays = 2}

This example shows how an ephemeris file is generated during an iterative process like differential correction that includes a discontinuous event like an impulsive burn. Ephemeris data is sent to text file called ‘EphemerisFile3.eph’:

Create Spacecraft aSat
Create Propagator aProp

Create ImpulsiveBurn TOI
Create DifferentialCorrector aDC

Create EphemerisFile anEphmerisFile

anEphmerisFile.Spacecraft = aSat
anEphmerisFile.Filename = 'EphemerisFile3.eph'

BeginMissionSequence

Propagate aProp(aSat) {aSat.Earth.Periapsis}

Target aDC
 Vary aDC(TOI.Element1 = 0.24, {Perturbation = 0.001, Lower = 0.0, ...
 Upper = 3.14159, MaxStep = 0.5})
 Maneuver TOI(aSat)
 Propagate aProp(aSat) {aSat.Earth.Apoapsis}
 Achieve aDC(aSat.Earth.RMAG = 42165)
EndTarget

Propagate aProp(aSat) {aSat.ElapsedDays = 1}

FiniteBurn

FiniteBurn — A finite burn

Description

The FiniteBurn resource is used when continuous propulsion is desired. Impulsive burns happen instantaneously through the use of the Maneuver command, while finite burns occur continuously starting at the BeginFiniteBurn command and lasting until the EndFiniteBurn command is reached in the mission sequence. In order to apply a non-zero Finite Burn, there must be a Propagate command between the BeginFiniteBurn and EndFiniteBurn commands.

See Also: FuelTank, Thruster, Spacecraft, BeginFiniteBurn, EndFiniteBurn

Fields

FieldDescription
Thruster

The Thruster field allows the selection of which Thruster, from a list of previously created thrusters, to use when applying a finite burn. Currently, using the GUI, you can only select  one Thruster to attach to a FiniteBurn resource. Using the scripting interface, you may attach multiple thrusters to a FiniteBurn resource. Using the scripting interface, you may attach multiple thrusters to a FiniteBurn resource. In a script command, an empty list, e.g., FiniteBurn1.Thruster={}, is allowed but is of limited utility since the GUI will automatically associate a Thruster, if one has been created, with the FiniteBurn. This field cannot be modified in the Mission Sequence.

Data Type

Reference Array

Allowed Values

Any Thruster created by user

Access

set

Default Value

No Default

Units

N/A

Interfaces

GUI, script, or only one

VectorFormat

Deprecated. Allows you to define the format of the finite burn thrust direction. This field has no affect. The finite burn thrust direction, as specified in the Thruster resource, is always given in Cartesian format.

Data Type

Enumeration

Allowed Values

Cartesian, Spherical

Access

set

Default Value

Cartesian

Units

N/A

Interfaces

script

GUI

The FiniteBurn dialog box allows you to specify which thruster to use for the finite burn. The layout of the FiniteBurn dialog box is shown below.

Remarks

Configuring a FiniteBurn

To perform a finite burn, the FiniteBurn resource itself and a number of related resources and commands must be properly configured. You must associate a specific Thruster hardware resource with a created FiniteBurn. You must associate a specific FuelTank hardware resource with the chosen Thruster. Finally, you must attach both the chosen Thruster and FuelTank to the desired Spacecraft. See the example below for additional details.

FiniteBurn Using Multiple Thrusters

Using the GUI, a FiniteBurn resource must be associated with exactly one Thruster. Future GMAT GUI versions will allow multiple thrusters to be attached to a single FiniteBurn resource.

Using the scripting interface, one can assign multiple thrusters to a single FiniteBurn resource.

Interactions

FieldDescription
Spacecraft resource

Must be created in order to apply any burn.

Thruster resource

As discussed in the Remarks, every FiniteBurn resource must be associated with at least one Thruster. Any Thruster created in the resource tree can be incorporated into a FiniteBurn.

FuelTank resource

To perform a finite burn, a FuelTank must be attached to the Spacecraft. (A FuelTank is needed to provide pressure and temperature data used when modeling the thrust and specific impulse. A FuelTank is also needed if you want to model mass depletion.)

BeginFiniteBurn and EndFiniteBurn command

After a FiniteBurn is created, to apply it in the mission sequence, a BeginFiniteBurn and EndFiniteBurn command must be appended to the mission tree.

Propagate command

In order to apply a non-zero finite burn, there must be a Propagate command between the BeginFiniteBurn and EndFiniteBurn commands.

Examples

Create a default Spacecraft and FuelTank Resource; Create a default Thruster that allows for fuel depletion from the default FuelTank; Attach FuelTank and Thruster to the Spacecraft; Create default ForceModel and Propagator; Create a Finite Burn that uses the default thruster and apply a 30 minute finite burn to the spacecraft.

% Create a default Spacecraft and FuelTank Resource
Create Spacecraft DefaultSC
Create FuelTank FuelTank1

% Create a default Thruster.  Allow for fuel depletion from 
% the default FuelTank.
Create Thruster Thruster1
Thruster1.DecrementMass = true
Thruster1.Tank = {FuelTank1}

%  Attach FuelTank and Thruster to the spacecraft
DefaultSC.Thrusters = {Thruster1}
DefaultSC.Tanks = {FuelTank1}

%  Create default ForceModel and Propagator
Create ForceModel DefaultProp_ForceModel
Create Propagator DefaultProp
DefaultProp.FM = DefaultProp_ForceModel

%  Create a Finite Burn that uses the default thruster
Create FiniteBurn FiniteBurn1
FiniteBurn1.Thrusters = {Thruster1}

BeginMissionSequence

%  Implement 30 minute finite burn
BeginFiniteBurn FiniteBurn1(DefaultSC)
Propagate DefaultProp(DefaultSC) {DefaultSC.ElapsedSecs = 1800}
EndFiniteBurn FiniteBurn1(DefaultSC)  

FminconOptimizer

FminconOptimizer — The Sequential Quadratic Processor (SQP) optimizer, fmincon

Description

fmincon is a Nonlinear Programming solver provided in MATLAB's Optimization Toolbox. fmincon performs nonlinear constrained optimization and supports linear and nonlinear constraints. To use this solver, you must configure the solver options including convergence criteria, maximum iterations, and how the gradients will be calculated. In the mission sequence, you implement an optimizer such as fmincon by using an Optimize/EndOptimize sequence. Within this sequence, you define optimization variables by using the Vary command, and define cost and constraints by using the Minimize and NonlinearConstraint commands respectively.

This resource cannot be modified in the Mission Sequence.

See Also: VF13ad,Optimize,Vary, NonlinearConstraint, Minimize

Fields

FieldDescription
DiffMaxChange

Upper limit on the perturbation used in MATLAB's finite differencing algorithm. For fmincon, you don't specify a single perturbation value, but rather give MATLAB a range, and it uses an adaptive algorithm that attempts to find the optimal perturbation.

Data Type

String

Allowed Values

Real Number > 0

Access

Set

Default Value

0.1

Units

None

Interfaces

GUI, script

DiffMinChange

Lower limit on the perturbation used in MATLAB's finite differencing algorithm. For fmincon, you don't specify a single perturbation value, but rather give MATLAB a range, and it uses an adaptive algorithm that attempts to find the optimal perturbation.

Data Type

String

Allowed Values

Real Number > 0

Access

Set

Default Value

1e-8

Units

None

Interfaces

GUI, script

MaxFunEvals

Specifies the maximum number of cost function evaluations used in an attempt to find an optimal solution. This is equivalent to setting the maximum number of passes through an optimization loop in a GMAT script. If a solution is not found before the maximum function evaluations, fmincon outputs an ExitFlag of zero, and GMAT continues.

Data Type

String

Allowed Values

Integer > 0

Access

Set

Default Value

1000

Units

None

Interfaces

GUI, script

MaximumIterations

Specifies the maximum allowable number of nominal passes through the optimizer.  Note that this is not the same as the number of optimizer iterations that is shown for the VF13ad optimzer.

Data Type

String

Allowed Values

Integer > 0

Access

Set

Default Value

25

Units

None

Interfaces

GUI, script

ReportFile

Contains the path and file name of the report file.

Data Type

String

Allowed Values

Any user-defined file name

Access

Set

Default Value

FminconOptimizerSQP1.data

Units

None

Interfaces

GUI, script

ReportStyle

Determines the amount and type of data written to the message window and to the report specified by field ReportFile for each iteration of the solver (when ShowProgress is true).  Currently, the Normal, Debug, and Concise options contain the same information: the values for the control variables, the constraints, and the objective function.  In addition to this information, the Verbose option also contains values of the optimizer-scaled control variables. 

Data Type

String

Allowed Values

Normal, Concise, Verbose, Debug

Access

Set

Default Value

Normal

Units

None

Interfaces

GUI, script

ShowProgress

Determines whether data pertaining to iterations of the solver is both displayed in the message window and written to the report specified by the ReportFile field. When ShowProgress is true, the amount of information contained in the message window and written in the report is controlled by the ReportStyle field.

Data Type

Boolean

Allowed Values

true, false

Access

Set

Default Value

true

Units

None

Interfaces

GUI, script

TolCon

Specifies the convergence tolerance on the constraint functions.

Data Type

String

Allowed Values

Real Number > 0

Access

Set

Default Value

1e-4

Units

None

Interfaces

GUI, script

TolFun

Specifies the convergence tolerance on the cost function value.

Data Type

String

Allowed Values

Real Number > 0

Access

Set

Default Value

1e-4

Units

None

Interfaces

GUI, script

TolX

Specifies the termination tolerance on the vector of independent variables, and is used only if the user sets a value for this field. 

Data Type

String

Allowed Values

Real Number > 0

Access

Set

Default Value

1e-4

Units

None

Interfaces

GUI, script

GUI

The FminconOptimizer dialog box allows you to specify properties of a FminconOptimizer resource such as maximum iterations, maximum function evaluations, control variable termination tolerance, constraint tolerance, cost function tolerance, finite difference algorithm parameters, and choice of reporting options.

To create a FminconOptimizer resource, navigate to the Resources tree, expand the Solvers folder, highlight and then right-click on the Optimizers sub-folder, point to Add and then select SQP (fmincon). This will create a new FminconOptimizer resource, SQP1. Double-click on SQP1 to bring up the FminconOptimizer dialog box shown below.

Remarks

fmincon Optimizer Availability

This optimizer is only available if you have access to both MATLAB and MATLAB's Optimization toolbox. GMAT contains an interface to the fmincon optimizer and it will appear to you that fmincon is a built in optimizer in GMAT. Field names for this resource have been copied from those used in MATLAB’S optimset function for consistency with MATLAB in contrast with other solvers in GMAT.

GMAT Stop Button Does Not work, in Some Situations, When Using Fmincon

Sometimes, when developing GMAT scripts, you may inadvertently create a situation where GMAT goes into an inifinite propagation loop. The usual remedy for this situation is to apply the GMAT Stop button. Currently, however, if the infinite loop occurs within an Optimize sequence using fmincon, there is no way to stop GMAT and you have to shut GMAT down. Fortunately, there are some procedures you can employ to avoid this situation. You should use multiple stopping conditions so that a long propagation cannot occur. For example, if fmincon controls variable, myVar, and we know myVar should never be more than 2, then do this.

Propagate myProp(mySat){mySat.ElapsedDays = myVar, mySat.ElapsedDays = 2}     

Resource and Command Interactions

The FminconOptimizer resource can only be used in the context of optimization-type commands. Please see the documentation for Optimize, Vary, NonlinearConstraint, and Minimize for more information and worked examples.

Examples

Create a FminconOptimizer resource named SQP1.

Create FminconOptimizer SQP1
SQP1.ShowProgress = true
SQP1.ReportStyle = Normal
SQP1.ReportFile = 'FminconOptimizerSQP1.data'
SQP1.MaximumIterations = 25
SQP1.DiffMaxChange = '0.1000'
SQP1.DiffMinChange = '1.0000e-08'
SQP1.MaxFunEvals = '1000'
SQP1.TolX = '1.0000e-04'
SQP1.TolFun = '1.0000e-04'
SQP1.TolCon = '1.0000e-04'           

For an example of how a FminconOptimizer resource can be used within an optimize sequence, see the Optimize command examples.


Formation

Formation — A collection of spacecraft.

Description

A Formation resource allows you to combine spacecraft in a “container” object and then GMAT’s propagation subsystem will model the collection of spacecraft as a coupled dynamic system. You can only propagate Formation resources using numerical-integrator type propagators. This resource cannot be modified in the Mission Sequence.

See Also: Propagate

Fields

FieldDescription
Add

Adds a list of Spacecraft to the Formation. The list cannot be empty.

Data Type

Resource array

Allowed Values

array of spacecraft

Access

set

Default Value

empty list

Units

N/A

Interfaces

GUI, script

GUI

To create a simple Formation and configure its Spacecraft, in the Resource Tree:

  1. Right-click the Spacecraft folder and select Add Spacecraft.

  2. Right click the Formations folder and select Add Formation.

  3. Double-click Formation1 to open its dialog box.

  4. Click the right-arrow button twice to add DefaultSC and Spacecraft1 to Formation1.

  5. Click Ok.

Note

A Spacecraft can only be added to one Formation.

Remarks

A Formation is a container object that allows you to model a group of Spacecraft as a coupled system. You can add Spacecraft to a Formation using the Add field as shown in the script examples below or in the GUI example above. The primary reasons to use a Formation Resource are (1) to simplify the propagation of multiple spacecraft and (2) for performance reasons. GMAT’s propagation subsystem models Formations as a coupled dynamic system. Once spacecraft have been added to a Formation, you can easily propagate all of the spacecraft by simply including the formation in the Propagate command statement like this:

Propagate aPropagator(aFormation) {aSat1.ElapsedSecs = 12000.0}

You can only propagate Formation resources using numerical-integrator type propagators. GMAT does not support propagation of the orbit state transition matrix when propagating formations.

When propagating a Formation, all spacecraft in the Formation must have equivalent epochs. GMAT will allow you to separately propagate a Spacecraft that has been added to a Formation, like this:

aFormation.Add = {aSat1, aSat2}
Propagate aPropagator(aSat1) {aSat1.ElapsedSecs = 12000.0}

However, when a Formation is propagated, if the epochs of all Spacecraft in the Formation are not equivalent to a tolerance of a few microseconds, GMAT will throw an error and execution will stop.

Examples

Create two Spacecraft, add them to a Formation, and propagate the Formation.

Create Spacecraft aSat1 aSat2

Create Formation aFormation
aFormation.Add = {aSat1, aSat2}

Create Propagator aPropagator

BeginMissionSequence

Propagate aPropagator(aFormation) {aSat1.ElapsedSecs = 12000.0}

FuelTank

FuelTank — Model of a chemical fuel tank

Description

A FuelTank is a thermodynamic model of a tank and is required for finite burn modeling or for impulsive burns that use mass depletion. The thermodynamic properties of the tank are modeled using Boyle’s law and assume that there is no temperature change in the tank as fuel is depleted. To use a FuelTank, you must first create the tank, and then attach it to the desired Spacecraft and associate it with a Thruster as shown in the example below.

See Also ImpulsiveBurn,Thruster

Fields

FieldDescription
AllowNegativeFuelMass

This field allows the FuelTank to have negative fuel mass which can be useful in optimization and targeting sequences before convergence has occurred. This field cannot be modified in the Mission Sequence.

Data Type

Boolean

Allowed Values

true, false

Access

set

Default Value

false

Units

N/A

Interfaces

GUI, script

FuelDensity

The density of the fuel.

Data Type

Real

Allowed Values

Real > 0

Access

set, get

Default Value

1260

Units

kg/m^3

Interfaces

GUI, script

FuelMass

The mass of fuel in the tank.

Data Type

Real

Allowed Values

Real > 0

Access

set, get

Default Value

756

Units

kg

Interfaces

GUI, script

Pressure

The pressure in the tank.

Data Type

Real

Allowed Values

Real > 0

Access

set, get

Default Value

1500

Units

kPa

Interfaces

GUI, script

PressureModel

The pressure model describes how pressure in the FuelTank changes as fuel is depleted. This field cannot be modified in the Mission Sequence.

Data Type

Enumeration

Allowed Values

PressureRegulated, BlowDown

Access

set

Default Value

PressureRegulated

Units

N/A

Interfaces

GUI, script

RefTemperature

The temperature of the tank when fuel was loaded.

Data Type

Real

Allowed Values

Real > -273.15 and |Real| > 0.01

Access

set, get

Default Value

20

Units

C

Interfaces

GUI, script

Temperature

The temperature of the fuel and ullage in the tank. GMAT currently assumes ullage and fuel are always at the same temperature.

Data Type

Real

Allowed Values

Real > -273.15

Access

set, get

Default Value

20

Units

C

Interfaces

GUI, script

Volume

The volume of the tank. GMAT checks to ensure that the input volume of the tank is larger than the calculated volume of fuel loaded in the tank and throws an exception in the case that the calculated fuel volume is larger than the input tank volume.

Data Type

Real

Allowed Values

Real > 0 such that calculated fuel volume is < input tank Volume.

Access

set, get

Default Value

0.75

Units

m^3

Interfaces

GUI, script

GUI

The FuelTank dialog box allows you to specify properties of a fuel tank including fuel mass, density, and temperature as well as tank pressure and volume. The layout of the FuelTank dialog box is shown below.

The Thruster resource is closely related to the FuelTank resource and thus, we also discuss it here. The Thruster dialog box allows you to specify properties of a thruster including the coordinate system of the Thrust acceleration direction vector, the thrust magnitude and Isp. The layout of the Thruster dialog box is shown below.

When performing a finite burn, you will typically want to model fuel depletion. To do this, select the Decrement Mass button and then select the previously created FuelTank as shown below.

Thus far, we have created both a FuelTank and a Thruster, and we have associated a FuelTank with our Thruster. We are not done yet. We must tell GMAT that we want to attach both the FuelTank and the Thruster to a particular spacecraft. To do this, double click on the desired spacecraft under the Spacecraft resource to bring up the associated GUI panel. Then click on the Tanks tab to bring up the following GUI display.

Next, select the desired FuelTank and use the right arrow button to attach the FuelTank to the spacecraft. Then, click the Apply button as shown below.

Similarly, to attach a Thruster to a spacecraft, double click on the desired spacecraft under the Spacecraft resource and then select the Actuators tab. Then select the desired thruster and use the right arrow to attach the thruster to the spacecraft. Finally, click the Apply button as shown below.

Remarks

Use of FuelTank Resource in Conjunction with Maneuvers

A FuelTank is used in conjunction with both impulsive and finite maneuvers. To implement an impulsive maneuver, one must first create an ImpulsiveBurn resource and (optionally) associate a FuelTank with it. The actual impulsive maneuver is implemented using the Maneuver command. See the Maneuver command documentation for worked examples on how the FuelTank resource is used in conjunction with impulsive maneuvers.

To implement a finite maneuver, you must first create both a Thruster and a FiniteBurn resource. You must also associate a FuelTank with the Thruster resource and you must associate a Thruster with the FiniteBurn resource. The actual finite maneuver is implemented using the BeginFiniteBurn/EndFiniteBurn commands. See the BeginFiniteBurn/EndFiniteBurn command documentation for worked examples on how the FuelTank resource is used in conjunction with finite maneuvers.

Behavior When Configuring Tank and Attached Tank Properties

Create a default FuelTank and attach it to a Spacecraft and Thruster.

%  Create the FuelTank Resource
Create FuelTank aTank
aTank.AllowNegativeFuelMass = false
aTank.FuelMass = 756
aTank.Pressure = 1500
aTank.Temperature = 20
aTank.RefTemperature = 20
aTank.Volume = 0.75
aTank.FuelDensity = 1260
aTank.PressureModel = PressureRegulated
%  Create a Thruster and assign it a FuelTank
Create Thruster aThruster
aThruster.Tank = {aTank}

%  Add the FuelTank and Thruster to a Spacecraft
Create Spacecraft aSpacecraft
aSpacecraft.Tanks = {aTank}
aSpacecraft.Thrusters = {aThruster}    

As exhibited below, there are some subtleties associated with setting and getting parent vs. cloned resources. In the example above, aTank is the parent FuelTank resource and the field aSpacecraft.Tanks is populated with a cloned copy of aTank.

Create a second spacecraft and attach a fuel tank using the same procedure used in the previous example. Set the FuelMass in the parent resource, aTank, to 900 kg.

%  Add the FuelTank and Thruster to a second Spacecraft
Create Spacecraft bSpacecraft
bSpacecraft.Tanks = {aTank}
bSpacecraft.Thrusters = {aThruster}
aTank.FuelMass = 900    %Can be performed in both resource and 
                        %command modes

Note that, in the example above, setting the value of the parent resource, aTank, changes the fuel mass value in both cloned fuel tank resources. More specifically, the value of both aSpacecraft.aTank.FuelMass and bSpacecraft.aTank.FuelMass are both now equal to the new value of 900 kg. We note that the assignment command for the parent resource, aTank.FuelMass, can be performed in both resource and command modes.

To change the value of the fuel mass in only the first created spacecraft, aSpacecraft, we do the following.

%  Create the Fuel Tank Resource
aTank.FuelMass = 756   %Fuel tank mass in both s/c set back to default
aSpacecraft.aTank.FuelMass = 1000 %Can only be performed in command mode.      

As a result of the commands in the previous example, the value of aSpacecraft.aTank.FuelMass is 1000 kg and the value of bSpacecraft.aTank.FuelMass is 756 kg. We note that the assignment command for the cloned resource, aSpacecraft.aTank.FuelMass, can only be performed in command mode.

Caution: Value of AllowNegativeFuelMass Flag Can Affect Iterative Processes

By default, GMAT will not allow the fuel mass to be negative. However, occasionally in iterative processes such as targeting, a solver will try values of a maneuver parameter that result in total fuel depletion. Using the default tank settings, this will throw an exception stopping the run unless you set the AllowNegativeFuelMass flag to true. GMAT will not allow the the total spacecraft mass to be negative. If DryMass + FuelMass is negative GMAT will throw an exception and stop.

Examples

Create a default FuelTank and attach it to a Spacecraft and Thruster.

%  Create the Fuel Tank Resource
Create FuelTank aTank
aTank.AllowNegativeFuelMass = false
aTank.FuelMass = 756
aTank.Pressure = 1500
aTank.Temperature = 20
aTank.RefTemperature = 20
aTank.Volume = 0.75
aTank.FuelDensity = 1260
aTank.PressureModel = PressureRegulated

%  Create a Thruster and assign it a FuelTank
Create Thruster aThruster
aThruster.Tank = {aTank}

%  Add the FuelTank and Thruster to a Spacecraft
Create Spacecraft aSpacecraft
aSpacecraft.Tanks = {aTank}
aSpacecraft.Thrusters = {aThruster}

BeginMissionSequence    

GroundStation

GroundStation — A ground station model.

Description

A GroundStation models a facility fixed to the surface of a CelestialBody. There are several state representations available for defining the location of a ground station including Cartesian and spherical. This resource cannot be modified in the Mission Sequence.

See Also: CoordinateSystem

Fields

FieldDescription
Altitude

The altitude of the station with respect to the HorizonReference.

Data Type

Real

Allowed Values

-∞ < Real < ∞

Access

set

Default Value

0

Units

km

Interfaces

GUI, script

CentralBody

The central body of the GroundStation.

Data Type

String

Allowed Values

Earth. (Ground stations are currenly only supported with respect to Earth)

Access

set

Default Value

Earth

Units

N/A

Interfaces

GUI, script

HorizonReference

The system used for the horizon. Sphere is equivalent to Geocentric, Ellipsoid is equivalent to Geodetic.

Data Type

String

Allowed Values

Sphere, Ellipsoid

Access

set

Default Value

Sphere

Units

N/A

Interfaces

GUI, script

Id

The Id of the GroundStation used in estimation and measurement modelling..

Data Type

String

Allowed Values

Must begin with a letter; may contain letters, integers, dashes, underscores

Access

set,

Default Value

StationId

Units

N/A

Interfaces

GUI, script

Latitude

The latitude of the station with respect to HorizonReference.

Data Type

Real

Allowed Values

-90 < Real < 90

Access

set

Default Value

0

Units

deg.

Interfaces

GUI, script

Location1

The first component of the GroundStation location. When StateType is Cartesian, Location1 is the x-component of station location in the body-fixed system. When StateType is Spherical or Elliposoid, Location1 is the Longitude (deg.) of the GroundStation.

Data Type

Real

Allowed Values

-∞ < Real < ∞ for Cartesian, See Longitude, Latitude, Altitude for others.

Access

set

Default Value

6378.1363

Units

see description

Interfaces

GUI, script

Location2

The second component of the GroundStation location. When StateType is Cartesian, Location2 is the y-component of station location in the body-fixed system. When StateType is Spherical or Ellipsoid, Location2 is the Latitude (deg.) of the GroundStation.

Data Type

Real

Allowed Values

-∞ < Real < ∞ for Cartesian, See Longitude, Latitude, Altitude for others.

Access

set

Default Value

0

Units

see description

Interfaces

GUI, script

Location3

The third component of the GroundStation location. When StateType is Cartesian, Location3 is the z-component of station location in the body-fixed system. When StateType is Spherical or Elliposoid, Location3 is the height (km) of the GroundStation above the reference shape.

Data Type

Reals

Allowed Values

-∞ < Real < ∞ for Cartesian, See Longitude, Latitude, Altitude for others.

Access

set,

Default Value

0

Units

see description

Interfaces

GUI, script

Longitude

The longitude of the station.

Data Type

Real

Allowed Values

value >=0

Access

set

Default Value

0

Units

deg.

Interfaces

GUI, script

StateType

The type of state used to define the location of the ground station. For example, Cartesian or Ellipsoid.

Data Type

String

Allowed Values

Cartesian, Spherical, Ellipsoid

Access

set

Default Value

Cartesian

Units

N/A

Interfaces

GUI, script

GUI

To create a GroundSation, starting from the Resource Tree:

  1. Right-click the GroundStation folder and select Add Ground Station.

  2. Double-click GroundStation1.

You can set the ground station location in several state representations. The Cartesian representation is illustrated above. To set the Longitude, Latitude, and Altitude to 45 deg., 270 deg., and 0.1 km respectively, with respect to the reference ellipsoid:

  1. In the StateType menu, select Spherical.

  2. In the HorizonReference menu, select Ellipsoid.

  3. In the Latitude text box, type 45.

  4. In the Longitude text box, type 270.

  5. In the Altitude text box, type 0.1.

Remarks

The GroundStation model allows you to configure a facility by defining the location in body-fixed coordinates using one of several state representations. GMAT supports Cartesian, Sphere, and Ellipsoid representations and examples below show how to configure a GroundStation in each representation. When using the Ellipsoid model or Sphere representations, GMAT uses the physical properties - flattening and radius for example - defined on the CelestialBody resource.

Examples

Configure a GroundStation in Geodetic coordinates.

Create GroundStation aGroundStation
aGroundStation.CentralBody      = Earth
aGroundStation.StateType        = Spherical
aGroundStation.HorizonReference = Ellipsoid
aGroundStation.Location1        = 60
aGroundStation.Location2        = 45
aGroundStation.Location3        = 0.01

% or alternatively

aGroundStation.Latitude  = 60
aGroundStation.Longitude = 45
aGroundStation.Altitude  = 0.01

Configure a GroundStation in Geocentric coordinates.

Create GroundStation aGroundStation
aGroundStation.CentralBody      = Earth
aGroundStation.StateType        = Spherical
aGroundStation.HorizonReference = Sphere
aGroundStation.Location1        = 59.83308194090783
aGroundStation.Location2        = 45
aGroundStation.Location3        = -15.99424674414058

% or alternatively

aGroundStation.Latitude        = 59.83308194090783
aGroundStation.Longitude       = 45
aGroundStation.Altitude        = -15.99424674414058

Configure a GroundStation in Geocentric coordinates.

Create GroundStation aGroundStation
aGroundStation.CentralBody = Earth
aGroundStation.StateType   = Cartesian
aGroundStation.Location1   = 2260.697433050543
aGroundStation.Location2   = 2260.697433050542
aGroundStation.Location3   = 5500.485954732006

GroundTrackPlot

GroundTrackPlot — A user-defined resource that draws longitude and latitude time-history of a spacecraft

Description

The GroundTrackPlot resource allows you to draw spacecraft’s longitude and latitude time-history onto the texture map of a user-selected central body. GMAT allows you to draw ground track plots of any number of spacecrafts onto a single texture map. You can also create multiple GroundTrackPlot resources by using either the GUI or script interface of GMAT. GMAT also provides the option of when to plot and stop plotting ground track of a spacecraft to a GroundTrackPlot through the Toggle On/Off command. See the Remarks section below for detailed discussion of the interaction between GroundTrackPlot resource and the Toggle command. GroundTrackPlot resource also allows you to display any number of user-defined ground stations onto the texture map of the central body.

See Also: Toggle, GroundStation

Fields

FieldDescription
Add

Allows the user to pick selected resources such as Spacecraft(s) or GroundStation(s) whose ground track is drawn in GroundTrackPlot. To select multiple Spacecrafts or GroundStations, seperate the list by comma and enclose the list in curly brackets. For Example: DefaultGroundTrackPlot.Add = {aSat, bSat, aGroundStaton, bGroundStation}. This field cannot be modified in the Mission Sequence.

Data Type

Reference Array

Allowed Values

Spacecraft, GroundStation

Access

Set

Default Value

DefaultSC

Units

N/A

Interfaces

GUI, script

CentralBody

The central body of the Ground track plot. This field cannot be modified in the Mission Sequence.

Data Type

Resource reference

Allowed Values

CelestialBody

Access

set

Default Value

Earth

Units

N/A

Interfaces

GUI, script

DataCollectFrequency

The number of integration steps to skip between plot points. This field cannot be modified in the Mission Sequence.

Data Type

Integer

Allowed Values

integer >= 1

Access

set

Default Value

1

Units

N/A

Interfaces

GUI, script

Maximized

Allows the user to maximize the GroundTrackPlot window. This field cannot be modified in the Mission Sequence.

Data Type

Boolean

Allowed Values

true,false

Access

set

Default Value

false

Units

N/A

Interfaces

script

NumPointsToRedraw

The number of plot points to retain and redraw during propagation and animation. 0 indicates to redraw all. This field cannot be modified in the Mission Sequence.

Data Type

Integer

Allowed Values

integer >= 0

Access

set

Default Value

0

Units

N/A

Interfaces

GUI, script

RelativeZOrder

Allows the user to select which GroundTrackPlot window to display first on the screen. The GroundTrackPlot with lowest RelativeZOrder value will be displayed last while GroundTrackPlot with highest RelativeZOrder value will be displayed first. This field cannot be modified in the Mission Sequence.

Data Type

Integer

Allowed Values

Integer ≥ 0

Access

set

Default Value

0

Units

N/A

Interfaces

script

ShowPlot

This field specifies whether to show ground track plot during a mission run. This field cannot be modified in the Mission Sequence.

Data Type

Boolean

Allowed Values

True, False

Access

set

Default Value

True

Units

N/A

Interfaces

GUI, script

Size

Allows the user to control the display size of GroundTrackPlot window. First value in [0 0] matrix controls horizonal size and second value controls vertical size of GroundTrackPlot display window. This field cannot be modified in the Mission Sequence.

Data Type

Real array

Allowed Values

Any Real number

Access

set

Default Value

[ 0 0 ]

Units

N/A

Interfaces

script

SolverIterations

This field determines whether or not ground track data associated with perturbed trajectories during a solver (Targeter, Optimize) sequence is displayed in the GroundTrackPlot. When SolverIterations is set to All, all perturbations/iterations are plotted in the GroundTrackPlot. When SolverIterations is set to Current, only the current solution or perturbation is plotted in GroundTrackPlot. When SolverIterations is set to None, only the final nominal run is plotted on the GroundTrackPlot.

Data Type

Enumeration

Allowed Values

All, Current, None

Access

set

Default Value

Current

Units

N/A

Interfaces

GUI, script

TextureMap

Allows you to enter or select any user-defined texture map image for the central body. This field cannot be modified in the Mission Sequence.

Data Type

String

Allowed Values

Valid File Path and Name

Access

set

Default Value

../data/graphics/texture/ModifiedBlueMarble.jpg

Units

N/A

Interfaces

GUI, script

UpdatePlotFrequency

The number of plot points to collect before updating a ground track plot. This field cannot be modified in the Mission Sequence.

Data Type

Integer

Allowed Values

integer > 1

Access

set

Default Value

50

Units

N/A

Interfaces

GUI, script

Upperleft

Allows the user to pan the GroundTrackPlot display window in any direction. First value in [0 0] matrix helps to pan the GroundTrackPlot window horizontally and second value helps to pan the window vertically. This field cannot be modified in the Mission Sequence.

Data Type

Real array

Allowed Values

Any Real number

Access

set

Default Value

[ 0 0 ]

Units

None

Interfaces

script

GUI

Default Name and Settings for the GroundTrackPlot Resource:

Remarks

Behavior when using GroundTrackPlot Resource & Toggle Command

The GroundTrackPlot resource draws the longitude and latitude time-history of a spacecraft at each propagation step of the entire mission duration. If you want to report data to a GroundTrackPlot at specific points in your mission, then a Toggle On/Off command can be inserted into the mission sequence to control when the GroundTrackPlot is to draw data. When Toggle Off command is issued for a GroundTrackPlot, no ground track data is drawn until a Toggle On command is issued. Similarly when a Toggle On command is used, ground track data is drawn at each integration step until a Toggle Off command is used.

Below is an example script snippet that shows how to use Toggle Off and Toggle On command while using the GroundTrackPlot resource. GroundTrackPlot is turned off for the first 2 days of the propagation:

Create Spacecraft aSat
Create Propagator aProp

Create GroundTrackPlot aGroundTrackPlot
aGroundTrackPlot.Add = {aSat}

BeginMissionSequence

Toggle aGroundTrackPlot Off
Propagate aProp(aSat) {aSat.ElapsedDays = 2}
Toggle aGroundTrackPlot On
Propagate aProp(aSat) {aSat.ElapsedDays = 4}

Behavior when Plotting Data in Iterative Processes

GMAT allows you to specify how data is plotted onto a plot during iterative processes such as differential correction or optimization. The SolverIterations field of GroundTrackPlot resource supports 3 options which are described in the table below:

SolverIterations optionsDescription
Current

Shows only current iteration/perturbation in an iterative process and draws current iteration to a plot

All

Shows all iterations/perturbations in an iterative process and draws all iterations/perturbations to a plot

None

Shows only the final solution after the end of an iterative process and draws only final solution to a plot

Behavior when Plotting Longitude and Latitude time-history of a Spacecraft

GMAT’s GroundTrackPlot resource allows you to draw longitude and latitude time-history of a spacecraft. You can choose to draw ground track plot of multiple spacecrafts onto a single texture map of a central body.

Warning

The longitude and latitude of a spacecraft is drawn as an approximation that includes straight line segments and longitude/latitude data does not takes into account central body shape or its oblateness.

Behavior When Specifying Empty Brackets in GroundTrackPlot's Add Field

When using GroundTrackPlot.Add field, if brackets are not populated with user-defined spacecrafts, then GMAT turns off GroundTrackPlot resource and no plot is generated. If you run the script with Add field having empty brackets, then GMAT throws in a warning message in the Message Window indicating that GroundTrackPlot resource will be turned off since no SpacePoints were added to the plot. Below is a sample script snippet that generates such a warning message:

Create Spacecraft aSat aSat2
Create Propagator aProp
Create GroundTrackPlot aGroundTrackPlot

aGroundTrackPlot.Add = {}

BeginMissionSequence;
Propagate aProp(aSat, aSat2) {aSat.ElapsedDays = 1}

Examples

This example shows how to use GroundTrackPlot resource. A single spacecraft and a ground station is added to the GroundTrackPlot. Spacecraft’s ground track is plotted for one day of propagation:

Create Spacecraft aSat
Create Propagator aProp

Create GroundStation aGroundStation

Create GroundTrackPlot aGroundTrackPlot
aGroundTrackPlot.Add = {aSat, aGroundStation}

BeginMissionSequence

Propagate aProp(aSat) {aSat.ElapsedDays = 1}

Propagate a spacecraft for two days around a non-default central body. Spacecraft’s ground track is plotted on planet Mars:

Create Spacecraft aSat
aSat.CoordinateSystem = MarsJ2000Eq
aSat.SMA = 8000
aSat.ECC = 0.0003

Create ForceModel aFM
aFM.CentralBody = Mars
aFM.PointMasses = {Mars}

Create Propagator aProp
aProp.FM = aFM

Create CoordinateSystem MarsJ2000Eq
MarsJ2000Eq.Origin = Mars
MarsJ2000Eq.Axes = MJ2000Eq

Create GroundTrackPlot aGroundTrackPlot
aGroundTrackPlot.Add = {aSat}
aGroundTrackPlot.CentralBody = Mars

BeginMissionSequence

Propagate aProp(aSat) {aSat.ElapsedDays = 2}

ImpulsiveBurn

ImpulsiveBurn — An impulsive maneuver

Description

The ImpulsiveBurn resource allows the spacecraft to undergo an instantaneous Delta-V (ΔV), as opposed to a finite burn which is not instantaneous, by specifying the three vector components of the Delta-V. You can configure the burn by defining its coordinate system and vector component values. For Local coordinate systems, the user can choose the Origin and type of Axes. Depending on the mission, it may be simpler to use one coordinate system over another.

See Also Maneuver,FuelTank,BeginFiniteBurn

Fields

FieldDescription
Axes

Allows you to define a spacecraft centered set of axes for the impulsive burn. This field cannot be modified in the Mission Sequence.

Data Type

String

Allowed Values

VNB, LVLH, MJ2000Eq, SpacecraftBody

Access

set

Default Value

VNB

Units

N/A

Interfaces

GUI, script

B

Deprecated. Z-component of the applied impulsive burn (Delta-V)

Data Type

Real

Allowed Values

Real

Access

set, get

Default Value

0

Units

km/s

Interfaces

GUI, script

CoordinateSystem

Determines what coordinate system the orientation parameters, Element1, Element2, and Element3 refer to. This field cannot be modified in the Mission Sequence.

Data Type

Reference Array

Allowed Values

Local, EarthMJ2000Eq, EarthMJ2000Ec, EarthFixed, or any user defined system

Access

set

Default Value

Local

Units

N/A

Interfaces

GUI, script

DecrementMass

Flag which determines if the FuelMass is to be decremented as it used. This field cannot be modified in the Mission Sequence.

Data Type

String

Allowed Values

true, false

Access

set

Default Value

false

Units

N/A

Interfaces

GUI, script

Element1

X-component of the applied impulsive burn (Delta-V)

Data Type

Real

Allowed Values

Real

Access

set, get

Default Value

0

Units

km/s

Interfaces

GUI, script

Element2

Y-component of the applied impulsive burn (Delta-V)

Data Type

Real

Allowed Values

Real

Access

set, get

Default Value

0

Units

km/s

Interfaces

GUI, script

Element3

Z-component of the applied impulsive burn (Delta-V)

Data Type

Real

Allowed Values

Real

Access

set, get

Default Value

0

Units

km/s

Interfaces

GUI, script

GravitationalAccel

Value of the gravitational acceleration used to calculate fuel depletion.

Data Type

Real

Allowed Values

Real > 0

Access

set, get

Default Value

9.81

Units

m/s^2

Interfaces

GUI, script

Isp

Value of the specific impulse of the fuel

Data Type

Real

Allowed Values

Real

Access

set, get

Default Value

300

Units

s

Interfaces

GUI, script

N

Deprecated. Y-component of the applied impulsive burn (Delta-V)

Data Type

Real

Allowed Values

Real

Access

set, get

Default Value

0

Units

km/s

Interfaces

GUI, script

Origin

The Origin field, used in conjunction with the Axes field, allows the user to define a spacecraft centered set of axes for the impulsive burn. This field cannot be modified in the Mission Sequence.

Data Type

Reference Array

Allowed Values

Sun, Mercury, Venus, Earth, Luna, Mars,Jupiter, Saturn, Uranus, Neptune, Pluto

Access

set

Default Value

Earth

Units

N/A

Interfaces

GUI, script

Tank

FuelTank from which the Thruster draws propellant from. This field cannot be modified in the Mission Sequence.

Data Type

Reference Array

Allowed Values

User defined list of FuelTanks

Access

set

Default Value

N/A

Units

N/A

Interfaces

GUI, script

V

Deprecated. X-component of the applied impulsive burn (Delta-V)

Data Type

Real

Allowed Values

Real

Access

set, get

Default Value

0

Units

km/s

Interfaces

GUI, script

VectorFormat

Deprecated. Allows you to define the format of the ImpulsiveBurn Delta-V Vector. This field has no affect. The ImpulsiveBurn Delta-V Vector is always given in Cartesian format.

Data Type

Enumeration

Allowed Values

Cartesian, Spherical

Access

set

Default Value

Cartesian

Units

N/A

Interfaces

script

GUI

The ImpulsiveBurn dialog box allows you to specify properties of an ImpulsiveBurn including Delta-V component values and choice of Coordinate System. If you choose to model fuel loss associated with an impulsive burn, you must specify choice of fuel tank as well as ISP value and gravitational acceleration used to calculate fuel use. The layout of the ImpulsiveBurn dialog box is shown below.

The Origin and Axes fields are only relevant if Coordinate System is set to Local. See the Remarks for more detail on local coordinate systems.

If Decrement Mass is checked, then you can select the desired FuelTank used as the fuel supply for mass depletion.

Remarks

Local Coordinate Systems

Here, a Local Coordinate System is defined as one that we configure "locally" using the ImpulsiveBurn resource interface as opposed to defining a coordinate system using the Coordinate Systems folder in the Resources Tree.

To configure a Local Coordinate System, you must specify the coordinate system of the input Delta-V vector, Element1-3. If you choose a local Coordinate System, the four choices available, as given by the Axes sub-field, are VNB, LVLH, MJ2000Eq, and SpacecraftBody. VNB or Velocity-Normal-Binormal is a non-inertial coordinate system based upon the motion of the spacecraft with respect to the Origin sub-field. For example, if the Origin is chosen as Earth, then the X-axis of this coordinate system is the along the velocity of the spacecraft with respect to the Earth, the Y-axis is along the instantaneous orbit normal (with respect to the Earth) of the spacecraft, and the Z-axis points away from the Earth as much as possible while remaining orthogonal to the other two axes, completing the right-handed set.

Similarly, Local Vertical Local Horizontal or LVLH is a non-inertial coordinate system based upon the motion of the spacecraft with respect to the body specified in the Origin sub-field. If you choose Earth as the origin, then the X-axis of this coordinate system points from the center of the Earth to the spacecraft, the Z-axis is along the instantaneous orbit normal (with respect to the Earth) of the spacecraft, and the Y-axis completes the right-handed set. For typical bound orbits, the Y-axis is approximately aligned with the velocity vector. In the event of a perfectly circular orbit, the Y axis is exactly along the velocity vector.

MJ2000Eq is the J2000-based Earth-centered Earth mean equator inertial Coordinate System. Note that the Origin sub-field is not needed to define this coordinate system.

SpacecraftBody is the coordinate system used by the spacecraft. Since the thrust is applied in this system, GMAT uses the attitude of the spacecraft, a spacecraft attribute, to determine the inertial thrust direction. Note that the Origin sub-field is not needed to define this coordinate system.

Deprecated Field Names for an ImpulsiveBurn

Note that the standard method, as shown below, for specifying the components of an ImpulsiveBurn is to use the Element1, Element2, and Element3 field names.

Create ImpulsiveBurn DefaultIB
DefaultIB.Element1 = -3
DefaultIB.Element2 = 7
DefaultIB.Element3 = -2    

For this current version of GMAT, you may also use the field names V, N, and B in place of Element1, Element2, and Element3, respectively. The commands below are equivalent to the commands above.

Create ImpulsiveBurn DefaultIB
DefaultIB.V = -3
DefaultIB.N = 7
DefaultIB.B = -2

It is important to note that the V, N, B field names do not necessarily correspond to some Velocity, Normal, Binormal coordinate system. The coordinate system of any ImpulsiveBurn is always specified by the CoordinateSystem, Origin, and Axes fields. Because of the confusion that the V, N, B field names can cause, their use will not be allowed in future versions of GMAT. If you use the V, N, B field names in this version of GMAT, you will receive a warning to this affect.

Interactions

ResourceDescription
Spacecraft resource

Must be created in order to apply any ImpulsiveBurn

FuelTank resource

If you want to model mass depletion for an ImpulsiveBurn, attach a FuelTank to the maneuvered Spacecraft as a source of fuel mass.

Maneuver command

Must use the Maneuver command to apply an ImpulsiveBurn to a Spacecraft.

Vary command

If you want to allow the ImpulsiveBurn components to vary in order to achieve some goal, then the Vary command, as part of a Target or Optimize command sequence, must be used.

Examples

Create a default FuelTank and an ImpulsiveBurn that allows for fuel depletion, assign the ImpulsiveBurn the default FuelTank, attach the FuelTank to a Spacecraft, and apply the ImpulsiveBurn to the Spacecraft.

%  Create the FuelTank Resource
Create FuelTank FuelTank1
FuelTank1.AllowNegativeFuelMass = false
FuelTank1.FuelMass = 756
FuelTank1.Pressure = 1500
FuelTank1.Temperature = 20
FuelTank1.RefTemperature = 20
FuelTank1.Volume = 0.75
FuelTank1.FuelDensity = 1260
FuelTank1.PressureModel = PressureRegulated

Create ImpulsiveBurn DefaultIB
DefaultIB.CoordinateSystem = Local
DefaultIB.Origin = Earth
DefaultIB.Axes = VNB
DefaultIB.Element1 = 0.001
DefaultIB.Element2 = 0
DefaultIB.Element3 = 0
DefaultIB.DecrementMass = true
DefaultIB.Tank = {FuelTank1}
DefaultIB.Isp = 300
DefaultIB.GravitationalAccel = 9.810000000000001

%  Add the the FuelTank to a Spacecraft
Create Spacecraft DefaultSC
DefaultSC.Tanks = {FuelTank1}

BeginMissionSequence
Maneuver DefaultIB(DefaultSC) 

LibrationPoint

LibrationPoint — An equilibrium point in the circular, restricted 3-body problem

Description

A LibrationPoint, also called a Lagrange point, is an equilibrium point in the circular restricted three-body problem (CRTBP). There are five libration points, three of which are unstable in the CRTBP sense, and two that are stable. See the discussion below for a detailed explanation of the different libration points and for examples configuring GMAT for common libration point regimes. This resource cannot be modified in the Mission Sequence.

See Also: Barycenter

Options

OptionDescription
Point

The libration point index.

Data Type

String

Allowed Values

L1, L2, L3, L4, or L5

Access

set

Default Value

L1

Units

N/A

Interfaces

GUI, script

Primary

The primary body or barycenter.

Data Type

String

Allowed Values

CelestialBody or Barycenter. Primary cannot be SolarSystemBarycenter and Primary cannot be the same as Secondary.

Access

set

Default Value

Sun

Units

N/A

Interfaces

GUI, script

Secondary

The secondary body or barycenter.

Secondary

String

Allowed Values

CelestialBody or Barycenter. Secondary cannot be SolarSystemBarycenter and Primary cannot be the same as Secondary.

Access

set

Default Value

Earth

Units

N/A

Interfaces

GUI, script

GUI

The LibrationPoint dialog box allows you to select the Primary Body, Secondary Body, and the libration point index. You can select from celestial bodies and barycenters. You cannot choose the SolarSystemBarycenter as either the Primary or Secondary and the Primary and Secondary cannot be the same object.

Remarks

Overview of Libration Point Geometry

A LibrationPoint, also called a Lagrange point, is an equilibrium point in the Circular Restricted Three Body Problem (CRTBP). The definitions for the libration points used in GMAT are illustrated in the figure below where the Primary and Secondary bodies are shown in a rotating frame defined with the x-axis pointing from the Primary to the Secondary. GMAT is configured for the full ephemeris problem and computes the location of the libration points by assuming that at a given instant in time, the CRTBP theory developed by Lagrange and Szebehely can be used to compute the location of the libration points using the locations of the primary and secondary from the JPL ephemerides. The three collinear points (L1, L2, and L3) are unstable (even in the CRTBP) and the triangular points (L4, and L5) are stable in CRTBP.

Configuring a Libration Point

GMAT allows you to define the Primary and/or Secondary as a CelestialBody or Barycenter (except SolarSystemBarycenter). This allows you to set the Primary as the Sun, and the Secondary as the Earth-Moon barycenter for modelling Sun-Earth-Moon libration points. See the examples below for details.

Examples

Create and use an Earth-Moon LibrationPoint.

%  Create the libration point and rotating libration point coordinate system
Create LibrationPoint EarthMoonL2
EarthMoonL2.Primary   = Earth
EarthMoonL2.Secondary = Luna
EarthMoonL2.Point     = L2

Create CoordinateSystem EarthMoonRotLibCoord
EarthMoonRotLibCoord.Origin    = EarthMoonL2
EarthMoonRotLibCoord.Axes      = ObjectReferenced
EarthMoonRotLibCoord.XAxis     = R
EarthMoonRotLibCoord.ZAxis     = N
EarthMoonRotLibCoord.Primary   = Earth
EarthMoonRotLibCoord.Secondary = Luna

%  Configure the spacecraft and propagator
Create Spacecraft aSat
aSat.DateFormat       = TAIModJulian
aSat.Epoch            = '25220.0006220895'
aSat.CoordinateSystem = EarthMoonRotLibCoord
aSat.DisplayStateType = Cartesian
aSat.X  = 9999.752137149568
aSat.Y  = 1.774296833900735e-007
aSat.Z  = 21000.02640446094
aSat.VX = -1.497748388797418e-005
aSat.VY = -0.2087816321971509
aSat.VZ = -5.42471673237177e-006

Create ForceModel EarthMoonL2Prop_ForceModel
EarthMoonL2Prop_ForceModel.PointMasses = {Earth, Luna, Sun}
Create Propagator EarthMoonL2Prop
EarthMoonL2Prop.FM = EarthMoonL2Prop_ForceModel

%  Create the orbit view
Create OrbitView ViewEarthMoonRot
ViewEarthMoonRot.Add                = {Earth, Luna, Sun,...
                                            aSat, EarthMoonL2}
ViewEarthMoonRot.CoordinateSystem   = EarthMoonRotLibCoord
ViewEarthMoonRot.ViewPointReference = EarthMoonL2
ViewEarthMoonRot.ViewDirection      = EarthMoonL2
ViewEarthMoonRot.ViewScaleFactor    = 5

Create Variable I

BeginMissionSequence

% Prop for 3 xz-plane crossings
For I = 1:3
  Propagate 'Prop to Y Crossing' EarthMoonL2Prop(aSat) ...
                      {aSat.EarthMoonRotLibCoord.Y = 0}
EndFor

Create and use a Sun, Earth-Moon LibrationPoint.

%  Create the Earth-Moon Barycenter and Libration Point
Create Barycenter EarthMoonBary
EarthMoonBary.BodyNames = {Earth,Luna}

Create LibrationPoint SunEarthMoonL1
SunEarthMoonL1.Primary   = Sun
SunEarthMoonL1.Secondary = EarthMoonBary
SunEarthMoonL1.Point     = L1

%  Create the coordinate system
Create CoordinateSystem RotatingSEML1Coord
RotatingSEML1Coord.Origin    = SunEarthMoonL1
RotatingSEML1Coord.Axes      = ObjectReferenced
RotatingSEML1Coord.XAxis     = R
RotatingSEML1Coord.ZAxis     = N
RotatingSEML1Coord.Primary   = Sun
RotatingSEML1Coord.Secondary = EarthMoonBary

%  Create the spacecraft and propagator
Create Spacecraft aSpacecraft
aSpacecraft.DateFormat       = UTCGregorian
aSpacecraft.Epoch            = '09 Dec 2005 13:00:00.000'
aSpacecraft.CoordinateSystem = RotatingSEML1Coord
aSpacecraft.X  = -32197.88223741966
aSpacecraft.Y  = 211529.1500044117
aSpacecraft.Z  = 44708.57017366499
aSpacecraft.VX = 0.03209516489451751
aSpacecraft.VY = 0.06100386504053736
aSpacecraft.VZ = 0.0550442738917212

Create Propagator aPropagator
aPropagator.FM           = aForceModel
aPropagator.MaxStep = 86400
Create ForceModel aForceModel
aForceModel.PointMasses = {Earth,Sun,Luna}

% Create a 3-D graphic
Create OrbitView anOrbitView
anOrbitView.Add                     = {aSpacecraft,  Earth, Sun, Luna}
anOrbitView.CoordinateSystem        = RotatingSEML1Coord
anOrbitView.ViewPointReference      = SunEarthMoonL1
anOrbitView.ViewPointVector         = [-1500000 0 0 ]
anOrbitView.ViewDirection           = SunEarthMoonL1
anOrbitView.ViewUpCoordinateSystem = RotatingSEML1Coord
anOrbitView.Axes                    = Off
anOrbitView.XYPlane                 = Off

BeginMissionSequence
           
Propagate aPropagator(aSpacecraft, {aSpacecraft.ElapsedDays = 180})

MatlabFunction

MatlabFunction — Declaration of an external MATLAB function

Description

The MatlabFunction resource declares to GMAT that the name given refers to an existing external function in the MATLAB language. This function can be called in the Mission Sequence like a built-in function, with some limitations. See the CallMatlabFunction reference for details. Both user-created functions and built-in functions (like cos or path) are supported.

GMAT supports passing data to and from MATLAB through the function. It requires that a supported and properly configured version of MATLAB exist on the system. See the MATLAB Interface documentation for general details on the interface.

See Also: CallMatlabFunction, MATLAB Interface

Fields

FieldDescription
FunctionPath

Paths to add to the MATLAB search path when the associated function is called. Separate multiple paths with semicolons (on Windows) or colons (on other platforms).

Data Type

String

Allowed Values

Valid file path(s)

Access

set, get

Default Value

MATLAB_FUNCTION_PATH properties in the startup file

Units

N/A

Interfaces

GUI, script

GUI

The MatlabFunction GUI window is very simple; it has a single file input box for the function path, and a Browse button that lets you graphically select the path.

Remarks

Search Path

When a function declared as a MatlabFunction is called, GMAT starts MATLAB in the background with a custom, configurable search path. MATLAB then searches for the named function in this search path. The search is case-sensitive, so the name of the function name and the MatlabFunction resource must be identical.

The search path consists of the following components, in order:

  1. FunctionPath field of the associated MatlabFunction resource (default: empty)

  2. MATLAB_FUNCTION_PATH entries in the GMAT startup file (default: GMAT\userfunctions\matlab)

  3. MATLAB search path (returned by the MATLAB path() function)

If multiple MATLAB functions are called within a run, the FunctionPath fields for each are prepended to the search path at the time of the function call.

Multiple paths can be combined in the FunctionPath field by separating the paths with a semicolon (on Windows) or a colon (on Mac OS X and Linux).

Working Directory

When MATLAB starts in the background, its working directory is set to the GMAT bin directory.

Examples

Call a simple built-in MATLAB function:

Create MatlabFunction sinh
Create Variable x y

BeginMissionSequence

x = 1
[y] = sinh(x)

Call an external custom MATLAB function:

Create Spacecraft aSat
Create ImpulsiveBurn aBurn
Create Propagator aProp

Create MatlabFunction CalcHohmann
CalcHohmann.FunctionPath = 'C:\path\to\functions'

Create Variable a_target mu dv1 dv2
mu = 398600.4415

BeginMissionSequence

% calculate burns for circular Hohmann transfer (example)
[dv1, dv2] = CalcHohmann(aSat.SMA, a_target, mu)

% perform first maneuver
aBurn.Element1 = dv1
Maneuver aBurn(aSat)

% propagate to apoapsis
Propagate aProp(aSat) {aSat.Apoapsis}

% perform second burn
aBurn.Element1 = dv2
Maneuver aBurn(aSat)

Return the MATLAB search path and working directory:

Create MatlabFunction path pwd
Create String pathStr pwdStr
Create ReportFile aReport

BeginMissionSequence

[pathStr] = path
[pwdStr] = pwd

Report aReport pathStr
Report aReport pwdStr

OrbitView

OrbitView — A user-defined resource that plots 3-Dimensional trajectories

Description

The OrbitView resource allows you to plot trajectories of a spacecraft or a celestial body. GMAT also allows you to plot trajectories associated with multiple spacecrafts or celestial bodies. You can create multiple OrbitView resources by using either the GUI or script interface of GMAT. OrbitView plots also come with multiple options that allow you to customize the view of spacecraft’s trajectories. See the Fields section below for detailed discussion on available plotting and drawing options.

GMAT also provides the option of when to start and stop plotting spacecraft’s trajectories to an OrbitView resource through the Toggle On/Off command. See the Remarks section below for detailed discussion of the interaction between an OrbitView resource and the Toggle command. GMAT’s Spacecraft, SolarSystem and OrbitView resources also interact with each other throughout the entire mission duration. Discussion of the interaction between these resources is also mentioned in the Remarks section.

See Also: Toggle, Spacecraft, SolarSystem, CoordinateSystem

Fields

FieldDescription
Add

This field allows you to add a Spacecraft, Celestial body, Libration Point, or Barycenter to a plot. When creating a plot, the Earth is added as a default body and may be removed by the user. The user can add a Spacecraft, Celestial body, Libration Point, or Barycenter to a plot by using the name used to create the resource. The GUI's Selected field is the equivalent of the script's Add field. In the event of no Add command or no resources in the Selected field, GMAT should run without the OrbitView plot and a warning message will be displayed in the message window. The following warning message is sufficient: The OrbitView named "DefaultOrbitView" will be turned off. No SpacePoints were added to plot. This field cannot be modified in the Mission Sequence.

Data Type

Reference Array

Allowed Values

Spacecraft, CelestialBody, LibrationPoint, Barycenter

Access

set

Default Value

DefaultSC, Earth

Units

N/A

Interfaces

GUI, script

Axes

Allows the user to tell GMAT to draw the Cartesian axis system associated with the coordinate system selected under the CoordinateSystem field of an OrbitView plot. This field cannot be modified in the Mission Sequence.

Data Type

Boolean

Allowed Values

On, Off

Access

set

Default Value

On

Units

N/A

Interfaces

GUI, script

EclipticPlane

Allows the user to tell GMAT to draw a grid representing the Ecliptic Plane in an OrbitView plot. This field cannot be modified in the Mission Sequence.

Data Type

Boolean

Allowed Values

On, Off

Access

set

Default Value

Off

Units

N/A

Interfaces

GUI, script

CoordinateSystem

Allows the user to select which coordinate system to use to draw the plot data. A coordinate system is defined as an origin and an axis system. The CoordinateSystem field allows the user to determine the origin and axis system of an OrbitView plot. See the CoordinateSystem resource fields for information of defining different types of coordinate systems. This field cannot be modified in the Mission Sequence.

Data Type

String

Allowed Values

CoordinateSystem resource

Access

set

Default Value

EarthMJ2000Eq

Units

N/A

Interfaces

GUI, script

DataCollectFrequency

Allows the user to define how data is collected for plotting. It is often inefficient to draw every ephemeris point associated with a trajectory. Often, drawing a smaller subset of the data still results in smooth trajectory plots, while executing more quickly. The DataCollectFrequency is an integer that represents how often to collect data and store for plotting. If DataCollectFrequency is set to 10, then data is collected every 10 integration steps. This field cannot be modified in the Mission Sequence.

Data Type

Integer

Allowed Values

Integer ≥ 1

Access

set

Default Value

1

Units

N/A

Interfaces

GUI, script

DrawObject

The DrawObject field allows the user the option of displaying Spacecraft or Celestial resources on the OrbitView plot. This field cannot be modified in the Mission Sequence.

Data Type

Boolean array

Allowed Values

true, false

Access

set

Default Value

[true true]

Units

N/A

Interfaces

GUI, script

EnableConstellations

Allows the user the option of displaying star constellations on the OrbitView Plot. This field cannot be modified in the Mission Sequence.

Data Type

Boolean

Allowed Values

On, Off

Access

set

Default Value

On

Units

N/A

Interfaces

GUI, script

EnableStars

Allows the user the option of displaying stars on the OrbitView Plot. When the EnableStars field is turned off, then EnableConstellations field is automatically diabled. This field cannot be modified in the Mission Sequence.

Data Type

Boolean

Allowed Values

On, Off

Access

set

Default Value

On

Units

N/A

Interfaces

GUI, script

Grid

Allows the user to draw a grid representing the longitude and latitude lines on the celestial bodies added to an OrbitView plot. This field cannot be modified in the Mission Sequence.

Data Type

Boolean

Allowed Values

On, Off

Access

set

Default Value

Off

Units

N/A

Interfaces

GUI, script

Maximized

Allows the user to maximize the OrbitView plot window. This field cannot be modified in the Mission Sequence.

Data Type

Boolean

Allowed Values

True, False

Access

set

Default Value

false

Units

N/A

Interfaces

script

NumPointsToRedraw

When NumPointsToRedraw field is set to zero, all ephemeris points are drawn. When NumPointsToRedraw is set to a positive integer, say 10 for example, only the last 10 collected data points are drawn. See DataCollectFrequency for explanation of how data is collected for an OrbitView plot. This field cannot be modified in the Mission Sequence.

Data Type

Integer

Allowed Values

Integer ≥ 1

Access

set

Default Value

0

Units

N/A

Interfaces

GUI, script

OrbitColor

Allows the user to be able to select colors for both spacecraft and celestial body trajectories. This field cannot be modified in the Mission Sequence.

Data Type

Integer Array

Allowed Values

Any color available from the Orbit Color selectbox

Access

set

Default Value

[ 255 32768 ]

Units

N/A

Interfaces

GUI, script

RelativeZOrder

Allows the user to select which OrbitView window to display first on the screen. The OrbitViewPlot with lowest RelativeZOrder value will be displayed last while OrbitViewPlot with highest RelativeZOrder value will be displayed first. This field cannot be modified in the Mission Sequence.

Data Type

Integer

Allowed Values

Integer ≥ 0

Access

set

Default Value

0

Units

N/A

Interfaces

script

ShowPlot

Allows the user to turn off a plot for a particular run, without deleting the plot, or removing it from the script. If you select true, then the plot will be shown. If you select false, then the plot will not be shown. This field cannot be modified in the Mission Sequence.

Data Type

Boolean

Allowed Values

True, False

Access

set

Default Value

True

Units

N/A

Interfaces

GUI, script

Size

Allows the user to control the display size of OrbitViewPlot window. First value in [0 0] matrix controls horizonal size and second value controls vertical size of OrbitViewPlot display window. This field cannot be modified in the Mission Sequence.

Data Type

Real array

Allowed Values

Any Real number

Access

set

Default Value

[0 0]

Units

N/A

Interfaces

script

SolverIterations

This field determines whether or not data associated with perturbed trajectories during a solver (Targeter, Optimize) sequence is plotted to OrbitView. When SolverIterations is set to All, all perturbations/iterations are plotted to an OrbitView plot. When SolverIterations is set to Current, only current solution is plotted to an OrbitView. When SolverIterations is set to None, this shows only final solution after the end of an iterative process and draws only final trajectory to an OrbitView plot.

Data Type

Enumeration

Allowed Values

All, Current, None

Access

set

Default Value

Current

Units

N/A

Interfaces

GUI, script

StarCount

Allows the user to enter the number of stars that need to be displayed in an OrbitView plot. This field cannot be modified in the Mission Sequence.

Data Type

Integer

Allowed Values

Integer ≥ 1

Access

set

Default Value

7000

Units

N/A

Interfaces

GUI, script

SunLine

Allows the user to tell GMAT to draw a line that starts at the center of central body and points towards the Sun. This field cannot be modified in the Mission Sequence.

Data Type

Boolean

Allowed Values

On, Off

Access

set

Default Value

Off

Units

N/A

Interfaces

GUI, script

TargetColor

Allows the user to select any available color for perturbing trajectories during iterative processes such as Differential Correction or Optimization. This field cannot be modified in the Mission Sequence.

Data Type

Integer array

Allowed Values

Any color available from Target Color select box

Access

set

Default Value

[ 8421440 0 ]

Units

N/A

Interfaces

GUI, script

UpdatePlotFrequency

Allows the user to specify how often to update an OrbitView plot is updated with new data collected during the process of propagating spacecraft and running a mission. Data is collected for a plot according to the value defined by DataCollectFrequency. An OrbitView plot is updated with the new data, according to the value set in UpdatePlotFrequency. If UpdatePlotFrequency is set to 10 and DataCollectFrequency is set to 2, then the plot is updated with new data every 20 (10*2) integration steps. This field cannot be modified in the Mission Sequence.

Data Type

Integer

Allowed Values

Integer ≥ 1

Access

set

Default Value

50

Units

N/A

Interfaces

GUI, script

UpperLeft

Allows the user to pan the OrbitView plot window in any direction. First value in [0 0] matrix helps to pan the OrbitView window horizontally and second value helps to pan the window vertically. This field cannot be modified in the Mission Sequence.

Data Type

Real array

Allowed Values

Any Real number

Access

set

Default Value

[0 0]

Units

N/A

Interfaces

script

UseInitialView

Allows the user to control the view of an OrbitView plot between multiple runs of a mission sequence. The first time a specific OrbitView plot is created, GMAT will automatically use the view as defined by the fields associated with View Definition, View Up Direction, and View Option. However, if the user changes the view using the mouse, GMAT will retain this view upon rerunning the mission as long as UseInitialView is set to false. If UseInitialView is set to true, the view for an OrbitView plot will be returned to the view defined by the initial settings. This field cannot be modified in the Mission Sequence.

Data Type

Boolean

Allowed Values

On, Off

Access

set

Default Value

On

Units

N/A

Interfaces

GUI, script

ViewDirection

Allows the user to select the direction of view in an OrbitView plot. The user can specify the view direction by choosing a resource to point at such as a Spacecraft, Celestial body, Libration Point, or Barycenter. Alternatively, the user can specify a vector of the form [x y z]. If the user specification of ViewDirection, ViewPointReference, and ViewPointVector results in a zero vector, GMAT uses [0 0 10000] for ViewDirection. This field cannot be modified in the Mission Sequence.

Data Type

Reference array

Allowed Values

Spacecraft, CelestialBody, LibrationPoint, Barycenter, or a 3-vector of numerical values

Access

set

Default Value

Earth

Units

km or N/A

Interfaces

GUI, script

ViewPointReference

This optional field that allows the user to change the reference point from which ViewPointVector is measured. ViewPointReference defaults to the origin of the coordinate system for the plot. A ViewPointReference can be any Spacecraft, Celestial body, Libration Point, or Barycenter. This field cannot be modified in the Mission Sequence.

Data Type

Reference array

Allowed Values

Spacecraft, CelestialBody, LibrationPoint, Barycenter, or a 3-vector of numerical values

Access

set

Default Value

Earth

Units

km or N/A

Interfaces

GUI, script

ViewPointVector

The product of ViewScaleFactor and ViewPointVector field determines the view point location with respect to ViewPointReference. ViewPointVector can be a vector, or any of the following resources: Spacecraft, Celestial body, Libration Point, or Barycenter. The location of the view point in three-dimensional space is defined as the vector addition of ViewPointReference and the vector defined by product of ViewScaleFactor and ViewPointVector in the coordinate system chosen by the user. This field cannot be modified in the Mission Sequence.

Data Type

Reference array

Allowed Values

Spacecraft, CelestialBody, LibrationPoint, Barycenter, or a 3-vector of numerical values

Access

set

Default Value

[30000 0 0]

Units

km or N/A

Interfaces

GUI, script

ViewScaleFactor

This field scales ViewPointVector before adding it to ViewPointReference. The ViewScaleFactor allows the user to back away from an object to fit in the field of view. This field cannot be modified in the Mission Sequence.

Data Type

Real

Allowed Values

Real Number ≥ 0

Access

set

Default Value

1

Units

N/A

Interfaces

GUI, script

ViewUpAxis

Allows the user to define which axis of the ViewUpCoordinateSystem field will appear as the up direction in an OrbitView plot. See the comments under ViewUpCoordinateSystem for more details of fields used to determine the up direction in an OrbitView plot. This field cannot be modified in the Mission Sequence.

Data Type

Enumeration

Allowed Values

X , -X , Y , -Y , Z , -Z

Access

set

Default Value

Z

Units

N/A

Interfaces

GUI, script

ViewUpCoordinateSystem

The ViewUpCoordinateSystem and ViewUpAxis fields are used to determine which direction appears as up in an OrbitView plot and together with the fields associated the the View Direction, uniquely define the view. The fields associated with the View Definition allow the user to define the point of view in three-dimensional space, and the direction of the line of sight. However, this information alone is not enough to uniquely define the view. We also must provide how the view is oriented about the line of sight. This is accomplished by defining what direction should appear as the up direction in the plot and is configured using the ViewUpCoordinateSystem field and the ViewUpAxis field. The ViewUpCoordinateSystem allows the user to select a coordinate system to define the up direction. Most of the time this system will be the same as the coordinate system chosen under the CoordinateSystem field. This field cannot be modified in the Mission Sequence.

Data Type

String

Allowed Values

CoordinateSystem resource

Access

set

Default Value

EarthMJ2000Eq

Units

N/A

Interfaces

GUI, script

WireFrame

When the WireFrame field is set to On, celestial bodies are drawn using a wireframe model. When the WireFrame field is set to Off, then celestial bodies are drawn using a full map. This field cannot be modified in the Mission Sequence.

Data Type

Boolean

Allowed Values

Off, On

Access

set

Default Value

Off

Units

N/A

Interfaces

GUI, script

XYPlane

Allows the user to tell GMAT to draw a grid representing the XY-plane of the coordinate system selected under the CoordinateSystem field of the OrbitView plot. This field cannot be modified in the Mission Sequence.

Data Type

Boolean

Allowed Values

On, Off

Access

set

Default Value

On

Units

N/A

Interfaces

GUI, script

GUI

The figure below shows the default settings for the OrbitView resource:

OrbitView Window Mouse Controls

The list of controls in the table below helps you navigate through the OrbitView graphics window. "Left" and "Right" designate the mouse button which have to be pressed.

ControlDescription
Left Drag

Helps to change camera orientation. Camera orientation can be changed in Up/Down/Left/Right directions.

Right Drag

Helps to zoom in and out of the graphics window. Moving the cursor in Up direction leads to zoom out of the graphics window. Moving the cursor in Down direction helps to zoom into the graphics window.

Shift+Right Drag

Helps to adjust the Field of View.

Remarks

Behavior when using OrbitView Resource & Toggle Command

The OrbitView resource plots spacecraft’s trajectory at each propagation step of the entire mission duration. If you want to report data to an OrbitView plot at specific points in your mission, then a Toggle On/Off command can be inserted into the mission sequence to control when OrbitView is to plot a given trajectory. When Toggle Off command is issued for an OrbitView, no trajectory is drawn until a Toggle On command is issued. Similarly, when a Toggle On command is used, trajectory is plotted at each integration step until a Toggle Off command is used.

Create Spacecraft aSat
Create Propagator aProp

Create OrbitView anOrbitView
anOrbitView.Add = {aSat, Earth}

BeginMissionSequence

Toggle anOrbitView Off
Propagate aProp(aSat) {aSat.ElapsedDays = 2}
Toggle anOrbitView On
Propagate aProp(aSat) {aSat.ElapsedDays = 4}

Behavior when using OrbitView, Spacecraft and SolarSystem Resources

Spacecraft resource contains information about spacecraft’s orbit. Spacecraft resource interacts with OrbitView throughout the entire mission duration. The trajectory data retrieved from the spacecraft is what gets plotted at each propagation step of the entire mission duration. Similarly, the sun and all other planets available under the SolarSystem resource may be plotted or referenced in the OrbitView resource as well.

Behavior when reporting data in Iterative Processes

GMAT allows you to specify how trajectories are plotted during iterative processes such as differential correction or optimization. The SolverIterations field of OrbitView resource supports 3 options which are described in the table below:

SolverIterations optionsDescription
Current

Shows only current iteration/perturbation in an iterative process and plots current trajectory.

All

Shows all iterations/perturbations in an iterative process and plots all perturbed trajectories.

None

Shows only the final solution after the end of an iterative process and plots only that final trajectory.

Behavior when plotting multiple spacecrafts

GMAT allows you to plot trajectories of any number of spacecrafts when using the OrbitView resource. The initial epoch of all the spacecrafts must be same in order to plot the trajectories. If initial epoch of one of the spacecrafts does not match with initial epoch of other spacecrafts, then GMAT throws in an error alerting you that there is a coupled propagation error mismatch between the spacecrafts. GMAT also allows you to propagate trajectories of spacecrafts using any combination of the propagators that the user creates.

Below is an example script snippet that shows how to plot trajectories of multiple spacecrafts that use different propagators:

Create Spacecraft aSat aSat2 aSat3
aSat2.INC = 45.0
aSat3.INC = 90.0
aSat3.SMA = 9000

Create Propagator aProp
Create Propagator bProp

Create OrbitView anOrbitView anOrbitView2

anOrbitView.Add = {aSat, aSat2, Earth}
anOrbitView2.Add = {aSat3, Earth}

BeginMissionSequence

Propagate aProp(aSat, aSat2) bProp(aSat3) {aSat.ElapsedSecs = 12000.0}

Behavior when using View Definition panel of OrbitView Resource

Currently in OrbitView resource’s View Definition panel, fields like ViewPointReference, ViewPointVector and ViewDirection are initialized but not dynamically updated during a mission run. OrbitView resource’s View Definition panel sets up geometry at initial epoch and then mouse controls geometry of the simulation from that point on.

Spacecraft Model Considerations in GMAT's OrbitView

GMAT displays spacecraft models by reading model data from 3D Studio files describing the spacecraft shape and colors. These files have the file extension .3ds, and are generally called 3ds files. 3ds files contain data that defines the 3-dimensional coordinates of vertices outlining the spacecraft, a mapping of those vertices into triangles used to create the displayed surface of the spacecraft, and information about the colors and texture maps used to fill in the displayed triangles.

GMAT's implementation of the spacecraft model can display models consisting of up to 200,000 vertices that map up to 100,000 triangles. The GMAT model can use up 500 separate color or texture maps to fill in these triangles.

Behavior When Specifying Empty Brackets in OrbitView's Add Field

When using OrbitView.Add field, if brackets are not populated with user-defined spacecrafts, then GMAT turns off OrbitView resource and no plot is generated. If you run the script with Add field having empty brackets, then GMAT throws in a warning message in the Message Window indicating that OrbitView resource will be turned off since no SpacePoints were added to the plot. Below is a sample script snippet that generates such a warning message:

Create Spacecraft aSat aSat2
Create Propagator aProp

Create OrbitView anOrbitView
anOrbitView.Add = {}

BeginMissionSequence
Propagate aProp(aSat, aSat2){aSat.ElapsedSecs = 12000.0}

Examples

Propagate spacecraft for 1 day and plot the orbit at every integrator step:

Create Spacecraft aSat
Create Propagator aProp

Create OrbitView anOrbitView
anOrbitView.Add = {aSat, Earth}

BeginMissionSequence

Propagate aProp(aSat) {aSat.ElapsedDays = 1}

Plotting orbit during an iterative process. Notice SolverIterations field is selected as All. This means all iterations/perturbations will be plotted.

Create Spacecraft aSat
Create Propagator aProp

Create ImpulsiveBurn TOI
Create DifferentialCorrector aDC

Create OrbitView anOrbitView
anOrbitView.Add = {aSat, Earth}
anOrbitView.SolverIterations = All

BeginMissionSequence

Propagate aProp(aSat) {aSat.Earth.Periapsis}

Target aDC
  Vary aDC(TOI.Element1 = 0.24, {Perturbation = 0.001, Lower = 0.0, ...
  Upper = 3.14159, MaxStep = 0.5})
  Maneuver TOI(aSat)
  Propagate aProp(aSat) {aSat.Earth.Apoapsis}
  Achieve aDC(aSat.Earth.RMAG = 42165)
EndTarget

Plotting spacecraft’s trajectory around non-default central body. This example shows how to plot a spacecraft’s trajectory around Luna:

Create Spacecraft aSat
  
Create CoordinateSystem LunaMJ2000Eq
LunaMJ2000Eq.Origin = Luna
LunaMJ2000Eq.Axes = MJ2000Eq

aSat.CoordinateSystem = LunaMJ2000Eq
aSat.SMA = 7300
aSat.ECC = 0.4
aSat.INC = 90
aSat.RAAN = 270
aSat.AOP = 315
aSat.TA = 180

Create ForceModel aFM
aFM.CentralBody = Luna
aFM.PointMasses = {Luna}

Create Propagator aProp
aProp.FM = aFM

Create OrbitView anOrbitView

anOrbitView.Add = {aSat, Luna}
anOrbitView.CoordinateSystem = LunaMJ2000Eq
anOrbitView.ViewPointReference = Luna
anOrbitView.ViewDirection = Luna

BeginMissionSequence

Propagate aProp(aSat) {aSat.ElapsedDays = 1}

Plotting spacecraft’s trajectory around non-default central body. This example shows how to plot a spacecraft’s trajectory around Mars:

Create Spacecraft aSat

Create CoordinateSystem MarsMJ2000Eq
MarsMJ2000Eq.Origin = Mars
MarsMJ2000Eq.Axes = MJ2000Eq

aSat.CoordinateSystem = MarsMJ2000Eq
aSat.SMA = 7300
aSat.ECC = 0.4
aSat.INC = 90
aSat.RAAN = 270
aSat.AOP = 315
aSat.TA = 180

Create ForceModel aFM
aFM.CentralBody = Mars
aFM.PointMasses = {Mars}

Create Propagator aProp
aProp.FM = aFM

Create OrbitView anOrbitView

anOrbitView.Add = {aSat, Mars}
anOrbitView.CoordinateSystem = MarsMJ2000Eq
anOrbitView.ViewPointReference = Mars
anOrbitView.ViewDirection = Mars

BeginMissionSequence

Propagate aProp(aSat) {aSat.ElapsedDays = 1}

Plotting spacecraft’s trajectory around non-default central body. This example shows how to plot a spacecraft’s trajectory around Sun. This is an interplanetary trajectory. Spacecraft is shown on an out-going hyperbolic trajectory in an EarthView and then an interplanetary trajectory is drawn around Sun in a SunView. Mars Orbit around Sun is also shown:

Create Spacecraft aSat

aSat.CoordinateSystem = EarthMJ2000Eq
aSat.DateFormat = UTCGregorian
aSat.Epoch = '18 Nov 2013 20:26:24.315'

aSat.X = 3728.345810006184
aSat.Y = 4697.943961035268
aSat.Z = -2784.040094879185
aSat.VX = -9.502477543864449
aSat.VY = 5.935188001372066
aSat.VZ = -2.696272103530009

Create ForceModel aFM
aFM.CentralBody = Earth
aFM.PointMasses = {Earth}

Create ForceModel bFM
aFM.CentralBody = Sun
aFM.PointMasses = {Sun}

Create Propagator aProp
aProp.FM = aFM

Create Propagator bProp
aProp.FM = bFM

Create CoordinateSystem SunEcliptic
SunEcliptic.Origin = Sun
SunEcliptic.Axes = MJ2000Ec

Create OrbitView EarthView SunView

EarthView.Add = {aSat, Earth}
EarthView.CoordinateSystem = EarthMJ2000Eq
EarthView.ViewPointReference = Earth
EarthView.ViewDirection = Earth

SunView.Add = {aSat, Mars, Sun}
SunView.CoordinateSystem = SunEcliptic
SunView.ViewPointReference = Sun
SunView.ViewDirection = Sun
SunView.ViewPointVector = [ 0 0 500000000 ]

BeginMissionSequence

Propagate aProp(aSat) {aSat.ElapsedDays = 3}
Propagate bProp(aSat) {aSat.ElapsedDays = 225}

Propagator

Propagator — A propagator models spacecraft motion

Overview of Propagator Components

A Propagator is the GMAT component used to model spacecraft motion. GMAT contains two types of propagators: a numerical integrator type, and an ephemeris type. When using a numerical integrator type Propagator, you can choose among a suite of numerical integrators implementing Runge-Kutta and predictor corrector methods. Numeric Propagators also require a ForceModel. Additionally, you can configure a Propagator to use SPICE kernels for propopagation. This resource cannot be modified in the Mission Sequence. However, you set one Propagator equal to another Propagator in the mission,( i.e. myPropagator = yourPropagator ).

GMAT's documentation for Propagator components is broken down into three sections:

See Also: Spacecraft, Propagate

Numerical Propagator

Overview

A Propagator object that uses a numerical integrator (as opposed to an ephemeris propagator) is one of a few objects in GMAT that is configured differently in the scripting and in the GUI. In the GUI, you configure the integrator and force model setting on the same dialog box. See the Remarks section below for detailed discussion of GMAT’s numerical integrators as well as performance and accuracy comparisons, and usage recommendations. This resource cannot be modified in the Mission Sequence. However, you can do whole object assignment in the mission,( i.e. myPropagator = yourPropagator ).

When working in the script, you must create a ForceModel object separately from the Propagator and specify the force model using the “FM” field on the propagator object. See the Examples section later in this section for details.

Options

OptionDescription
Accuracy

The desired accuracy for an integration step. GMAT uses the method selected in the ErrorControl field on the Force Model to determine a metric of the integration accuracy. For each step, the integrator ensures that the error in accuracy is smaller than the value defined by the ErrorControl metric.

Data Type

Real

Allowed Values

Real > 0 AND Real < 1

Default Value

1e-11 except for ABM integrator which is 1e-10

Interfaces

GUI, script

Access

set

Units

N/A

FM

Identifies the force model used by an integrator. If no force model is provided, GMAT uses an Earth centered propagator with a 4x4 gravity model.

Data Type

Resource reference

Allowed Values

ForceModel

Default Value

N/A

Interfaces

GUI, script

Access

set

Units

N/A

InitialStepSize

The size of the first step attempted by the integrator.

Data Type

Real

Allowed Values

Real > 0.0001

Default Value

60

Interfaces

GUI, script

Access

set

Units

sec.

LowerError

The lower bound on integration error, used to determine when to make the step size larger. Applies only to AdamsBashforthMoulton integrator.

Data Type

Real

Allowed Values

Real > 0 AND 0 < LowerError <TargetError < Accuracy

Default Value

1e-13

Interfaces

GUI, script

Access

set

Units

N/A

MaxStep

The maximum allowable step size.

Data Type

Real

Allowed Values

Real > 0 AND MinStep <= MaxStep

Default Value

2700

Interfaces

GUI, script

Access

set

Units

N/A

MaxStepAttempts

The number of attempts the integrator takes to meet the tolerance defined by the Accuracy field.

Data Type

Integer

Allowed Values

Integer >= 1

Default Value

50

Interfaces

GUI, script

Access

set

Units

N/A

MinStep

The minimum allowable step size.

Data Type

Real

Allowed Values

Real > 0 AND MinStep <= MaxStep

Default Value

0.001

Interfaces

GUI, script

Access

set

Units

sec.

StopIfAccuracy-IsViolated

Flag to stop propagation if integration error value defined by Accuracy is not satisfied.

Data Type

Boolean

Allowed Values

true, false

Default Value

true

Interfaces

GUI, script

Access

set

Units

N/A

TargetError

The nominal bound on integration error, used to set the target integration accuracy when adjusting step size. Applies only to AdamsBashforthMoulton integrator.

Data Type

Real

Allowed Values

Real > 0 AND 0 < LowerError < TargetError < Accuracy

Default Value

1e-11

Interfaces

GUI, script

Access

set

Units

N/A

Type

Specifies the integrator or analytic propagator used to model the time evolution of spacecraft motion.

Data Type

Enumeration

Allowed Values

PrinceDormand78, PrinceDormand45, RungeKutta89,RungeKutta68, RungeKutta56, AdamsBashforthMoulton, SPK

Default Value

RungeKutta89

Interfaces

GUI, script

Access

set

Units

N/A

GUI

Settings for the embedded Runge-Kutta integrators. Select the desired integrator from the Type menu.

The Adams-Bashforth-Moulton integrator has additional settings as shown.

Remarks

Best Practices for Using Numerical Integrators

The comparison data presented in a later section suggest that the PrinceDormand78 integrator is the best all purpose integrator in GMAT. When in doubt, use the PrinceDormance78 integrator, and set MinStep to zero so that the integrator’s adaptive step algorithm controls the minimum integration step size. Below are some important comments on GMAT’s step size control algorithms and the dangers of using a non-zero value for the minimum integration step size. The AdamsBashforthMoulton integrator is a low order integrator and we only recommend its use for low precision analysis when a predictor-corrector algorithm is required. We recommend that you study the performance and accuracy analysis documented later in this section to select a numerical integrator for your application. You may need to perform further analysis and comparisons for your application.

Caution

Caution: GMAT’s default error computation mode is RSStep and this is a more stringent error control method than RSSState that is often used as the default in other software such as STK. If you set Accuracy to a very small number, 1e-13 for example, and leave ErrorControl set to RSSStep, integrator performance will be poor, for little if any improvement in the accuracy of the orbit integration. To find the best balance between integration accuracy and performance, we recommend you experiment with the accuracy setting for your selected integrator for your application. You can start with a relatively high setting of Accuracy, say 1e-9, and lower the accuracy by an order of magnitude at a time and compare the final orbital states to determine where smaller values of Accuracy result in longer propagation times without providing more accurate orbital solutions.

Caution

Caution: GMAT allows you to set a minimum step on numerical integrators. It is possible that the requested Accuracy cannot be achieved given the MinimumStep setting. The Propagator flag StopIfAccuracyIsViolated determines the behavior if Accuracy cannot be satisfied. If StopIfAccuracyIsViolated is true, GMAT will throw an error and stop execution if integration accuracy is not satisfied. If StopIfAccuracyIsViolated is false, GMAT will only throw a warning that the integration accuracy was not satisfied but will continue to propagate the orbit.

Numerical Integrators Overview

The table below describes each numerical integrator in detail.

OptionDescription
RungeKutta89

An adaptive step, ninth order Runge-Kutta integrator with eighth order error control. The coefficients were derived by J. Verner. Verner developed several sets of coefficients for an 89 integrator and we have chosen the coefficients that are the most robust but not necessarily the most efficient.

PrinceDormand78

An adaptive step, eighth order Runge-Kutta integrator with seventh order error control. The coefficients were derived by Prince and Dormand.

PrinceDormand45An adaptive step, fifth order Runge-Kutta integrator with fourth order error control. The coefficients were derived by Prince and Dormand.
RungeKutta68

A second order Runge-Kutta-Nystrom type integrator with coefficients developed by by Dormand, El-Mikkawy and Prince. The integrator is a 9-stage Nystrom integrator, with error control on both the dependent variables and their derivatives. This second order implementation will correctly integrate forces that are non-conservative but it is not recommended for this use. See the integrator comparisons below for numerical comparisons. You cannot use this integrator to integrate mass during a finite maneuver because the mass flow rate is a first order differential equation not supported by this integrator.

RungeKutta56

An adaptive step, sixth order Runge-Kutta integrator with fifth order error control. The coefficients were derived by E. Fehlberg.

AdamsBashforthMoulton

A fourth-order Adams-Bashford predictor / Adams-Moulton corrector as described in Fundamentals of Astrodynamics by Bate, Mueller, and White. The predictor step extrapolates the next state of the variables using the the derivative information at the current state and three previous states of the variables. The corrector uses derivative information evaluated for this state, along with the derivative information at the original state and two preceding states, to tune this state, giving the final, corrected state. The ABM integrator uses the RungeKutta89 integrator to start the integration process. The ABM is a low order integrator and should not be used for precise applications or for highly nonlinear applications such as celestial body flybys.

Performance & Accuracy Comparison of Numerical Integrators

The tables below contain performance comparison data for GMAT's numerical integrators. The first table shows the orbit types, dynamics models, and propagation duration for each test case included in the comparison. Five orbit types were compared: low earth orbit, Molniya, Mars transfer (Type 2), Lunar transfer, and finite burn (case 1 is blow down, and case 2 is pressure regulated). For each test case, the orbit was propagated forward for a duration and then back-propagated to the intial epoch. The error values in the table are the RSS difference of the final position after forward and backward propagation to the initial position. The run time data for each orbit type is normalized on the integrator with the fasted run time for that orbit type. For all test cases the ErrorControl setting was set to RSSStep. Accuracy was set to 1e-12 for all integrators except for AdamsBashfourthMoulton which was set to 1e-11 because of poor performance when Accuracy was set to 1e-11.

OrbitDynamics ModelDuration
LEO

Earth 20x20, Sun, Moon, drag using MSISE90 density, SRP

1 day

Molniya

Earth 20x20, Sun, Moon, drag using Jacchia Roberts density, SRP

3 days

Mars Transfer

Near Earth: Earth 8x8, Sun, Moon, SRP

Deep Space: All planets as point mass perturbations

Near Mars: Mars 8x8 SRP

333 days

Lunar Transfer

Earth central body with all planets as point mass perturbations

5.8 days

Finite Burn (case 1 and 2)

Point mass gravity

7200 sec.

Comparing the run time data for each integrator shown in the table below we see that the PrinceDormand78 integrator was the fastest for 4 of the 6 cases and tied with the RungeKutta89 integrator for LEO test case. For the Lunar flyby case, the RungeKutta89 was the fastest integrator, however, in this case the PrinceDormand78 integrator was at least 2 orders of magnitude more accurate given equaivalent Accuracy settings. Notice that the AdamsBashforthMoulton integrator has km level errors for some orbits because it is a low-order integrator.

Fields Unique to the AdamsBashforthMoulton Integrator

The AdamsBashforthMoulton integrator has two additional fields named TargetError and LowerError that are only active when Type is set to AdamsBashforthMoulton. If you are using another integrator type, those fields must be removed from your script file to avoid parsing errors. When working in the GUI, this is performed automatically. See examples below for more details.

Examples

Propagate an orbit using a general purpose Runge-Kutta integrator:

Create Spacecraft aSat
Create ForceModel aForceModel

Create Propagator aProp
aProp.FM              = aForceModel
aProp.Type            = PrinceDormand78
aProp.InitialStepSize = 60
aProp.Accuracy        = 1e-011
aProp.MinStep         = 0
aProp.MaxStep         = 86400
aProp.MaxStepAttempts = 50
aProp.StopIfAccuracyIsViolated = true

BeginMissionSequence

Propagate aProp(aSat) {aSat.ElapsedDays = .2}

Propagate using a fixed step configuration. Do this by setting InitialStepSize to the desired fixed step size and setting ErrorControl to None. This example propagates in constant steps of 30 seconds:

Create Spacecraft aSat
Create ForceModel aForceModel
aForceModel.ErrorControl = None

Create Propagator aProp
aProp.FM              = aForceModel
aProp.Type            = PrinceDormand78
aProp.InitialStepSize = 30

BeginMissionSequence

Propagate aProp(aSat) {aSat.ElapsedDays = .2}

Propagate an orbit using an Adams-Bashforth-Moulton predictor-corrector integrator:

Create Spacecraft aSat
Create ForceModel aForceModel
aForceModel.ErrorControl = RSSStep

Create Propagator aProp
aProp.FM              = aForceModel
aProp.Type            = AdamsBashforthMoulton
aProp.InitialStepSize = 60
aProp.MinStep         = 0
aProp.MaxStep         = 86400
aProp.MaxStepAttempts = 50
%  Note the following fields must be set with decreasing values!
aProp.Accuracy        = 1e-010
aProp.TargetError     = 1e-011
aProp.LowerError      = 1e-013
aProp.StopIfAccuracyIsViolated = true

BeginMissionSequence

Propagate aProp(aSat) {aSat.ElapsedDays = .2}

Force Model

Overview

A ForceModel is a model of the environmental forces and dynamics that affect the motion of a spacecraft. GMAT supports numerous force models such as point mass and spherical harmonic gravity models, atmospheric drag, solar radiation pressure, tide models, and relativistic corrections. A ForceModel is configured and attached to the Propagator object (see the Propagator object for differences between script and GUI configuration when configuring a Propagator). The Propagator, along with the Propagate command, uses a ForceModel to numerically solve the orbital equations of motion (forwards or backwards in time) using the forces configured in the ForceModel object, and may include thrust terms in the case of powered flight. See the discussion below for detailed information on how to configure force models for your application. This resource cannot be modified in the Mission Sequence.

See Also: Propagator

Fields

OptionDescription
CentralBody

The central body of propagation. CentralBody must be a celestial body and cannot be a LibrationPoint, Barycenter, Spacecraft, or other special point.

Data Type

Resource reference

Allowed Values

CelestialBody

Access

set

Default Value

Earth

Units

N/A

Interfaces

GUI, script

Drag

Deprecated. This field has been replaced with Drag.AtmosphereModel.

Drag.AtmosphereModel

Specifies the atmosphere model used in the drag force. This field is only active if there is a PrimaryBody.

Data Type

Enumeration

Allowed Values

None, JacchiaRoberts, MSISE86, MSISE90, NRLMSISE00.

Access

set

Default Value

MSISE90

Units

N/A

Interfaces

GUI, script

Drag.F107

The instantaneous value of solar flux at wavelength of 10.7 cm. This field is only active if there is a PrimaryBody.

Data Type

Real

Allowed Values

50 <= Drag.F107 <= 400

Access

set

Default Value

150

Units

W/m^2/Hz

Interfaces

GUI, script

Drag.F107A

The average (monthly) value of solar flux at wavelength of 10.7 cm. This field is only active in the script if there is a PrimaryBody.

Data Type

Real

Allowed Values

50 <= Drag.F107A <= 400

Access

set

Default Value

150

Units

W/m^2/Hz

Interfaces

script

Drag.MagneticIndex

The geomagnetic index (Kp) used in density calculations. Kp is a planetary 3-hour-average, geomagnetic index that measures magnetic effects of solar radiation. This field is only active if there is a PrimaryBody.

Data Type

Real

Allowed Values

0 <= Real Number <= 9

Access

set

Default Value

3

Units

N/A

Interfaces

script

ErrorControl

Controls how error in the current integration step is estimated. The error in the current step is computed by the selection of ErrorControl and compared to the value set in the Accuracy field to determine if the step has an acceptable error or needs to be improved. All error measurements are relative error, however, the reference for the relative error changes depending upon the selection of ErrorControl. RSSStep is the Root Sum Square (RSS) relative error measured with respect to the current step. RSSState is the (RSS) relative error measured with respect to the current state. LargestStep is the state vector component with the largest relative error measured with respect to the current step. LargestState is the state vector component with the largest relative error measured with respect to the current state. Setting ErrorControl to None turns off error control and the integrator takes constant steps at the value defined by InitialStepSize on the numerical integrator.

Data Type

Enumeration

Allowed Values

None, RSSStep, RSSState, LargestState, LargestStep

Access

set

Default Value

RSSStep

Units

N/A

Interfaces

GUI, script

GravityField.​Earth.EarthTideModel

Flag for type of Earth tide model. This field is always active but only used in the dynamics when there is a harmonic gravity model for Earth.

Data Type

Enumeration

Allowed Values

None, SolidAndPole

Access

set

Default Value

None

Units

N/A

Interfaces

script

GravityField.​PrimaryBodyName.Degree

The degree of the harmonic gravity field. This field is only active if there is a PrimaryBody.

Data Type

Integer

Allowed Values

0<Degree<Max Degree On File

Access

set

Default Value

4 (When loading a custom file in the GUI, GMAT sets Degree to the max value on the file)

Units

N/A

Interfaces

GUI, script

GravityField.​PrimaryBodyName.Order

The order of the harmonic gravity field. This field is only active if there is a PrimaryBody.

Data Type

Integer

Allowed Values

0<Order<Max Degree On File AND Degree <= Order

Access

set

Default Value

4 (When loading a custom file in the GUI, GMAT sets Order to the max value on the file)

Units

N/A

Interfaces

GUI, script

GravityField.​PrimaryBodyName.PotentialFile

The gravity potential file. This field is only active if there is a PrimaryBody. See discussion below for detailed explanation of supported file types and how to configure gravity files.

Data Type

String

Allowed Values

path and name of .cof OR .grv file

Access

set

Default Value

JGM2.cof

Units

N/A

Interfaces

GUI, script

Model

A GUI list of "configured' gravity files defined in the file gmat_startup_file.txt. Model allows you to quickly choose between gravity files distributed with GMAT. For example, if PrimaryBody is Earth, you can select among Earth gravity models provided with GMAT such as JGM-2 and EGM-96. If you select Other, you can provide the path and filename for a custom gravity file.

Data Type

String

Allowed Values

JGM-2, JGM-3, EGM-96, Mars-50C, MGNP-180U

Access

set,get

Default Value

JGM-2

Units

N/A

Interfaces

GUI

PointMasses

A list of celestial bodies to be treated as point masses in the force model. A body cannot be both the PrimaryBody and in the PointMasses list. An empty list "{}" removes all points masses from the list.

Data Type

Resource array

Allowed Values

array of CelestialBodies not selected as PrimaryBody

Access

set

Default Value

Empty List

Units

N/A

Interfaces

GUI, script

PrimaryBodies

A body modeled with a "complex" force model. A primary body can have an atmosphere and harmonic gravity model. Currently GMAT only supports one primary body per force model. The primary body must be the same as the CentralBody, and cannot be included in the PointMasses field.

Data Type

Resource reference

Allowed Values

CelestialBody not included in PointMasses.

Access

set

Default Value

Earth

Units

N/A

Interfaces

GUI, script

RelativisticCorrection

Sets relativistic correction on or off.

Data Type

Enumeration

Allowed Values

On, Off

Access

set

Default Value

Off

Units

N/A

Interfaces

GUI, script

SRP

Sets SRP force on or off. See the Remarks section for a detailed explanation of SRP configuration.

Data Type

Enumeration

Allowed Values

On, Off

Access

set

Default Value

Off

Units

N/A

Interfaces

GUI, script

SRP.Flux

The value of SRP flux at 1 AU. This field is only active in the script if SRP is on.

Data Type

Real

Allowed Values

1300 <SRP.Flux < 1450

Access

set

Default Value

1367

Units

W/m^2

Interfaces

script

SRP.Flux_Pressure

The solar flux at 1 AU divided by the speed of light. This field is only active in the script if SRP is on. See the Remarks section for a detailed explanation of SRP configuration.

Data Type

Real

Allowed Values

4.33e-6 < SRP.Flux_Pressure < 4.84e-6

Access

set

Default Value

4.55982118135874e-006

Units

W *s/m^3

Interfaces

script

SRP.Nominal_Sun

The value of one Astronomical Unit in km used in scaling SRP.Flux, which is flux at 1 AU, to the flux at spacecraft distance from sun. This field is only active in the script if SRP is on. See the Remarks section for a detailed explanation of SRP configuration.

Data Type

Real

Allowed Values

135e6<Nominal_Sun<165e6

Access

set

Default Value

149597870.691

Units

km

Interfaces

script

GUI

Settings for the ForceModel object.

Remarks

Overview of Primary Body/Central Body and Field Interactions

In GMAT, a primary body is a celestial body that is modeled with a complex force model which may include a spherical harmonic gravity model, tides, or drag. A body cannot appear in both the PrimaryBodies and PointMasses fields. GMAT currently requires that there are no more than one primary body per ForceModel, but this behavior will change in future versions and the user interface is designed to naturally support this future development area.

GMAT currently requires that the primary body is either the same as the CentralBody or set to None. If you change the CentralBody in the GUI, GMAT changes the primary body to None, and you can then select between None and the central body. When you select a primary body in the GUI, the Gravity and Drag fields activate and allow you to select models for those forces consistent with the body selected in the PrimaryBodies field. For example, if you select Earth as the primary body, you can only select Earth drag models in the Drag.AtmosphereModel field. See the field list above for available models.

Configuring Gravitational Models

GMAT supports point mass gravity, spherical harmonic, and Earth tide models. On a Propagator, all celestial bodies are classified into two mutually exclusive categories: PrimaryBodies, and Point Masses. To model a body as a point mass, add it to the PointMasses list. GMAT currently requires that there be only a single body in the PrimaryBodies list. When a primary body is selected, the CentralBody and primary body must be the same.

Bodies modeled as PointMasses use the gravitational parameter defined on the body (i.e. Earth.Mu) in the equations of motion. Bodies defined as PrimaryBodies use the constants defined on the potential file in the equations of motion. GMAT supports two gravity file formats: the .cof format and the STK .grv format. You can provide a custom potential file for your application as long as it is one of the supported formats. Potential files defined in the startup file are available in the Model list in the GUI. For example, the following lines in the startup file configure GMAT so that EGM96 is an available option for Model in the GUI when the primary body is Earth:

EARTH_POT_PATH         = DATA_PATH/gravity/earth/
EGM96_FILE             = EARTH_POT_PATH/EGM96.cof 

Below is an example script snippet for configuring a custom gravity model including Earth tides.

Create ForceModel aForceModel
aForceModel.CentralBody = Earth
aForceModel.PrimaryBodies = {Earth}
aForceModel.GravityField.Earth.Degree = 21
aForceModel.GravityField.Earth.Order  = 21
aForceModel.GravityField.Earth.PotentialFile = 'c:\MyData\File.cof'
aForceModel.GravityField.Earth.EarthTideModel = 'SolidAndPole'

Configuring Drag Models

GMAT supports many density models for Earth including Jacchia-Roberts and various MSISE models. Density models for non-Earth bodies -- the Mars-GRAM model for example -- are included using custom plug-in components and are currently only supported in the script interface.

To configure Earth density models, select Earth as the primary body, In the GUI, this activates the AtmosphereModel list. You can configure the solar flux values using the Setup button next to the AtmosphereModel list after you have selected an atmosphere model. Below is an example script snippet for configuring the NRLMSISE00 density model.

Create ForceModel aForceModel
GMAT aForceModel.PrimaryBodies = {Earth}
GMAT aForceModel.Drag.AtmosphereModel = NRLMSISE00
GMAT aForceModel.Drag.F107 = 145
GMAT aForceModel.Drag.F107A = 160
GMAT aForceModel.Drag.MagneticIndex = 4

Caution

Caution: GMAT uses the original single precision FORTAN code developed by the scientists who created the MSISE models. At low altitudes, the single precision density can cause numeric issues in the double precision integrator step size control and integration can be unacceptably slow. You can avoid the performance issue by using either fixed step integration or by using a relatively high Accuracy value such as 1e-8. You may need to experiment with the Accuracy setting to a value acceptable for your application.

Note that when you select None for Drag.AtmosphereModel , the fields Drag.F107, Drag.F107A, and Drag.MagneticIndex are inactive and must be removed from your script file to avoid parsing errors. When working in the GUI, this is performed automatically.

The table below describes the limits on altitude for drag models supported by GMAT.

ModelTheoretical Altitude (h) LimitsComments
MSISE86

90 < h < 1000

GMAT will not allow propagation below 90 km altitude.

MSISE90

0 < h <1000

GMAT will allow propagation below 0 km altitude but results are non-physical.

NRLMSISE000 < h <1000

GMAT will allow propagation below 0 km altitude but results are non-physical.

JacchiaRoberts

h > 100

GMAT will not allow propagation below 100 km altitude.

Configuring an SRP Model

GMAT uses a dual cone model to model central body shadowing of the spacecraft and models solar radiation pressure using a spherical spacecraft model. You can define the solar flux using two approaches which are currently only supported in the script interface. One approach is to define the flux value using the SRP.Flux field and the value of an astronomical unit (in km) using the Nominal_Sun field as shown in the following example.

Create ForceModel aForceModel
GMAT aForceModel.PrimaryBodies = {Earth}
GMAT aForceModel.SRP = On
GMAT aForceModel.SRP.Flux = 1367
GMAT aForceModel.SRP.Nominal_Sun = 149597870.691

An alternative approach is to define the flux pressure at 1 astronomical unit using the Flux_Pressure field as shown below..

Create ForceModel aForceModel
GMAT aForceModel.PrimaryBodies = {Earth}
GMAT aForceModel.SRP = On
GMAT aForceModel.SRP.Flux_Pressure = 4.53443218374393e-006
GMAT aForceModel.SRP.Nominal_Sun = 149597870.691

If you mix flux settings, as shown in the example below, GMAT will use the last approach in the script. Here, GMAT will use the Flux_Pressure setting.

Create ForceModel aForceModel
GMAT aForceModel.PrimaryBodies = {Earth}
GMAT aForceModel.SRP = On
GMAT aForceModel.SRP.Flux = 1370
GMAT aForceModel.SRP.Nominal_Sun = 149597870
GMAT aForceModel.SRP.Flux_Pressure = 4.53443218374393e-006

Caution

Caution: GMAT’s default option for configuring solar flux for an SRP model is to use SRP.Flux and Nominal_Sun fields. If you initially configured the Flux_Pressure field, when you save your mission via the save button in the toolbar, GMAT will write out SRP.Flux and Nominal_Sun values consistent with your setting of Flux_Pressure.

Variational Equations and the STM

GMAT can optionally propagate the orbit State Transition Matrix (STM). For more information on how to configure GMAT to compute the STM, see the Propagate command documentation.

Caution

Caution: GMAT allows you to propagate the State Transition Matrix (STM) along with the orbital state. However, not all variational terms are implemented for STM propagation. The following are implemented: point mass perturbation, spherical harmonics (with tide models), and solar radiation pressure. The following are NOT implemented: drag and relativistic terms, and finite burns. Additionally, the SRP variational term does not include the partial derivative of the percent shadow with respect to orbital state. This approximation is acceptable for orbits with short penumbra durations but is inaccurate for orbits that spend relatively long periods of time in penumbra.

Examples

A ForceModel for point mass propagation.

Create Spacecraft aSat

Create ForceModel aForceModel
aForceModel.CentralBody = Earth
aForceModel.PointMasses = {Earth}

Create Propagator aProp
aProp.FM = aForceModel

BeginMissionSequence

Propagate aProp(aSat) {aSat.ElapsedDays = .2}

A ForceModel for high fidelity low Earth orbit propagation.

Create Spacecraft aSat

Create ForceModel aForceModel
aForceModel.CentralBody = Earth
aForceModel.PrimaryBodies = {Earth}
aForceModel.PointMasses = {Sun, Luna}
aForceModel.SRP = On
aForceModel.RelativisticCorrection = On
aForceModel.ErrorControl = RSSStep
aForceModel.GravityField.Earth.Degree = 20
aForceModel.GravityField.Earth.Order = 20
aForceModel.GravityField.Earth.PotentialFile = 'EGM96.cof'
aForceModel.GravityField.Earth.EarthTideModel = 'None'
aForceModel.Drag.AtmosphereModel = MSISE90
aForceModel.Drag.F107 = 150
aForceModel.Drag.F107A = 150
aForceModel.Drag.MagneticIndex = 3
aForceModel.SRP.Flux = 1359.388569998901
aForceModel.SRP.Nominal_Sun = 149597870.691

Create Propagator aProp
aProp.FM = aForceModel

BeginMissionSequence

Propagate aProp(aSat){aSat.ElapsedDays = .2}

A ForceModel for high fidelity lunar orbit propagation.

Create Spacecraft moonSat
GMAT moonSat.DateFormat = UTCGregorian
GMAT moonSat.Epoch.UTCGregorian = 01 Jun 2004 12:00:00.000
GMAT moonSat.CoordinateSystem = MoonMJ2000Eq
GMAT moonSat.DisplayStateType = Cartesian
GMAT moonSat.X = -1486.792117191545200
GMAT moonSat.Y = 0.0
GMAT moonSat.Z = 1486.792117191543000
GMAT moonSat.VX = -0.142927729144255
GMAT moonSat.VY = -1.631407624437537
GMAT moonSat.VZ = 0.142927729144255

Create CoordinateSystem MoonMJ2000Eq
MoonMJ2000Eq.Origin = Luna
MoonMJ2000Eq.Axes   = MJ2000Eq

Create ForceModel MoonLP165P
GMAT MoonLP165P.CentralBody = Luna
GMAT MoonLP165P.PrimaryBodies = {Luna}
GMAT MoonLP165P.SRP = On
GMAT MoonLP165P.SRP.Flux = 1367
GMAT MoonLP165P.SRP.Nominal_Sun = 149597870.691
GMAT MoonLP165P.Gravity.Luna.PotentialFile = ../data/gravity/luna/LP165P.cof
GMAT MoonLP165P.Gravity.Luna.Degree = 20
GMAT MoonLP165P.Gravity.Luna.Order = 20

Create Propagator RKV89
GMAT RKV89.FM = MoonLP165P

BeginMissionSequence

Propagate RKV89(moonSat) {moonSat.ElapsedSecs = 300}

SPK-Configured Propagator

Description

An SPK-configured Propagator propagates a spacecraft by interpolating user-provided SPICE kernels. You configure a Propagator to use an SPK kernel by setting the Type field to SPK. SPK kernels and the NAIFId are defined on the Spacecraft Resource. You control propagation, including stopping conditions, using the Propagate command. This resource cannot be modified in the Mission Sequence. However, you can do whole object assignment in the mission,( i.e. myPropagator = yourPropagator ).

See Also: Spacecraft, Propagate

Fields

FieldDescription
CentralBody

The central body of propagation. This field has no affect for SPK propagators.

Data Type

Resource reference

Allowed Values

Celestial body

Access

set

Default Value

Earth

Units

N/A

Interfaces

GUI, script

EpochFormat

Only used for an SPK propagator. The format of the epoch contained in the StartEpoch field.

Data Type

Enumeration

Allowed Values

A1ModJulian, TAIModJulian, UTCModJulian, TTModJulian, TDBModJulian, A1Gregorian, TAIGregorian, TTGregorian, UTCGregorian, TDBGregorian

Access

set

Default Value

A1ModJulian

Units

N/A unless Mod Julian and in that case Modified Julian Date

Interfaces

GUI, script

Start Epoch

Only used for an SPK propagator. The initial epoch of propagation. When an epoch is provided that epoch is used as the initial epoch. When the keyword "FromSpacecraft" is provided, the start epoch is inherited from the spacecraft.

Data Type

String

Allowed Values

"Gregorian: 04 Oct 1957 12:00:00.000 <= Epoch <= 28 Feb 2100 00:00:00.000 Modified Julian: 6116.0 <= Epoch <= 58127.5 or "FromSpacecraft"

Access

set

Default Value

21545

Units

N/A

Interfaces

GUI, script

StepSize

The step size for an SPK Propagator.

Data Type

Real

Allowed Values

Real > 0

Access

set

Default Value

300

Units

N/A

Interfaces

GUI, script

Type

Specifies the integrator or analytic propagator used to model time evolution of spacecraft motion.

Data Type

Enumeration

Allowed Values

PrinceDormand78, PrinceDormand45, RungeKutta89,RungeKutta68, RungeKutta56, BulirschStoer, AdamsBashforthMoulton, SPK

Access

set

Default Value

RungeKutta89

Units

N/A

Interfaces

GUI, script

GUI

To configure a Propagator to use SPK files, on the Propagator dialog box, select SPK in the Type menu. There are four fields you can configure for an SPK propagator including StepSize, CentralBody, EpochFormat, and StartEpoch. Note that changing the EpochFormat setting converts the input epoch to the selected format. You can also type FromSpacecraft into the StartEpoch field and the Propagator will use the epoch of the Spacecraft as the initial propagation epoch.

Remarks

To use an SPK-configured Propagator, you must specify the SPK kernels and NAIFId on the Spacecraft, configure a Propagator to use SPK files as opposed to numerical methods, and configure the Propagate command to use the configured SPK propagator. The subsections and examples below discuss each of these items in detail.

Configuring Spacecraft SPK Kernels

To use an SPK-configured Propagator, you must add the SPK kernels to the Spacecraft and define the pacecraft's NAIFId. SPK Kernels for selected spacecraft are available here. Two sample vehicle spk kernels, (GEOSat.bsp and MoonTransfer.bsp) are distributed with GMAT for example purposes. An example of how to add spacecraft kernels via the script interface is shown below.

Create Spacecraft aSpacecraft
GMAT aSpacecraft.NAIFId = -123456789
GMAT aSpacecraft.OrbitSpiceKernelName = {...
                                    '..\data\vehicle\ephem\spk\GEOSat.bsp'}

To add Spacecraft SPK kernals via the GUI:

  1. On the Spacecraft dialog box, click the SPICE tab.

  2. Under the SPK Files list, click Add.

  3. Browse to locate and select the desired SPK file

  4. Repeat to add all necessary SPK kernels

  5. In the NAIF ID field, enter the spacecraft integer NAIF id number. Note: For a given mission, each spacecraft should have a unique NAIF ID if the spacecraft are propagated with an SPK propagator.

You can add more than one kernel to a spacecraft as shown via scripting below, where the files GEOSat1.bsp and GEOSat2.bsp are dummy file names used for example purposes only and are not distributed with GMAT. In the script, you can use relative path or absolute path to define the location of an SKP file. Relative paths are defined with respect to the GMAT bin directory of your local installation.

Create Spacecraft aSpacecraft
aSpacecraft.OrbitSpiceKernelName ={'C:\MyDataFiles\GEOSat1.bsp',...
                                   'C:\MyDataFiles\GEOSat2.bsp'}

Configuring an SPK Propagator

You can define the StartEpoch of propagation of an SPK-configured Propagator on either the Propagator Resource or inherit the StartEpoch from the Spacecraft. Below is a script snippet that shows how to inherit the StartEpoch from the Spacecraft. To inherit the StartEpoch from the Spacecraft using the GUI

  1. Open the SPK propagator dialog box,

  2. In the StartEpoch field., type FromSpacecraft or select FromSpacecraft from the drop-down menu

To explicitly define the StartEpoch on the Propagator Resource use the following syntax.

Create Propagator spkProp
spkProp.EpochFormat = 'UTCGregorian'
spkProp.StartEpoch = '22 Jul 2014 11:29:10.811'

Create Propagator spkProp2
spkProp2.EpochFormat = 'TAIModJulian'
spkProp2.StartEpoch = '23466.5'

To configure the step size, use the StepSize field.

Create Propagator spkProp
spkProp.Type = SPK
spkProp.StepSize = 300

Interaction with the Propagate Command

An SPK-configured Propagator works with the Propagate command in the same way numerical propagators work with the Propagate command with the following exceptions:

  • If a Propagate command uses an SPK propagator, then you can only propagate one spacecraft using that propagator. You can however, mix SPK propagators and numeric propagators in a single propagate command.

  • SPK-configured Propagators will not propagate the STM or compute the orbit Jacobian (A matrix).

In the example below, we assume a Spacecraft named aSpacecraft and a Propagator named spkProp have been configured a-priori. An example command to propagate aSpacecraft to Earth Periapsis using spkProp is shown below.

Propagate spkProp(aSpacecraft) {aSpacecraft.Earth.Periapsis}

Below is a script snippet that demonstrates how to propagate backwards using an SPK propagator.

Propagate BackProp spkProp(aSpacecraft) {aSpacecraft.ElapsedDays = -1.5}

Behavior Near Ephemeris Boundaries

In general, ephemeris interpolation is less accurate near the boundaries of ephemeris files and we recommend providing ephemeris for significant periods beyond the initial and final epochs of your application for this and other reasons. When propagating near the beginning or end of ephemeris files, the use of the double precision arithmetic may affect results. For example, if an ephemeris file has has an initial epoch TDBModJulian = 21545.00037249916, and you specify the StartEpoch in UTC Gregorian, round off error in time conversions and/or truncation of time using the Gregorian format (only accurate to millisecond) may cause the requested epoch to fall slightly outside of the range provided on the ephemeris file. The best solution is to provide extra ephemeris data to avoid time issues at the boundaries and the more subtle issue of poor interpolation.

Warning

To locate requested stopping conditions, GMAT needs to bracket the root of the stopping condition function. Then, GMAT uses standard root finding techniques to locate the stopping condition to the requested accuracy. If the requested stopping condition lies at or near the beginning or end of the ephemeris data, then bracketing the stopping condition may not be possible without stepping off the ephemeris file which throw an error and execution will stop. In this case, you must provide more ephemeris data to locate the desired stopping condition.

Examples

Propagate a GEO spacecraft using an SPK-configured Propagator. Define the StartEpoch from the spacecraft. Note: the SPK kernel GEOSat.bsp is distributed with GMAT.

Create Spacecraft aSpacecraft;
aSpacecraft.Epoch.UTCGregorian = '02 Jun 2004 12:00:00.000'
aSpacecraft.NAIFId = -123456789
aSpacecraft.OrbitSpiceKernelName = {'..\data\vehicle\ephem\spk\GEOSat.bsp'}

Create Propagator spkProp
spkProp.Type = SPK
spkProp.StepSize = 300
spkProp.CentralBody = Earth
spkProp.StartEpoch = FromSpacecraft

Create OrbitView EarthView
EarthView.Add = {aSpacecraft, Earth, Luna}
EarthView.ViewPointVector = [ 30000 -20000 10000 ]
EarthView.ViewScaleFactor = 2.5

BeginMissionSequence
Propagate spkProp(aSpacecraft) {aSpacecraft.TA = 90}
Propagate spkProp(aSpacecraft) {aSpacecraft.ElapsedDays = 2.4}

Simulate a lunar transfer using an SPK-configured Propagator. Define StartEpoch on the Propagator. Note: the SPK kernel MoonTransfer.bsp is distributed with GMAT.

Create Spacecraft aSpacecraft
aSpacecraft.NAIFId = -123456789
aSpacecraft.OrbitSpiceKernelName = {...
                          '..\data\vehicle\ephem\spk\MoonTransfer.bsp'}

Create Propagator spkProp
spkProp.Type = SPK
spkProp.StepSize = 300
spkProp.CentralBody = Earth
spkProp.EpochFormat = 'UTCGregorian'
spkProp.StartEpoch = '22 Jul 2014 11:29:10.811'

Create OrbitView EarthView
EarthView.Add = {aSpacecraft, Earth, Luna}
EarthView.ViewPointVector = [ 30000 -20000 10000 ]
EarthView.ViewScaleFactor = 30

BeginMissionSequence
Propagate spkProp(aSpacecraft) {aSpacecraft.ElapsedDays = 12}

ReportFile

ReportFile — Report data to a text file

Description

The ReportFile resource allows you to write data to a text file that can be viewed after a mission run has been completed. GMAT allows you to report user-defined Variables, Arrays, Strings and Object Parameters. GMAT gives you control over setting formatting properties of the output report file that is generated at the end of a mission run. You can create ReportFile resource in either the GUI or script interface. GMAT also provides the option of when to write and stop writing data to a text file through the Toggle On/Off command. See the Remarks section below for detailed discussion of the interaction between ReportFile resource and Toggle command.

See Also: Report, Toggle

Fields

FieldDescription
Add

Allows a user to add any number of user-defined Variables, Arrays, Strings or Object Parameters to a report file. To add multiple user-defined variables or parameters, enclose the reported values with curly brackets. Ex. MyReportName.Add ={Sat.X, Sat.Y, Var1, Array(1,1)}; The GUI's Selected Value(s) field is the equivalent of the script's Add field. This field cannot be modified in the Mission Sequence.

Data Type

Reference array

Allowed Values

Any user-defined parameter. Ex. Variables, Arrays, Strings, or Object parameters

Access

set

Default Value

{DefaultSC.A1ModJulian, DefaultSC.EarthMJ2000Eq.X}

Units

N/A

Interfaces

GUI, script

ColumnWidth

This field defines the width of the data columns in a report file. The value for ColumnWidth is applied to all columns of data. For example, if ColumnWidth is set to 20, then each data column will be 20 white-spaces wide.

Data Type

Integer

Allowed Values

Integer > 1

Access

set

Default Value

20

Units

Characters

Interfaces

GUI, script

Filename

Allows the user to define the file path and file name for a report file.

Data Type

String

Allowed Values

Valid File Path and Name

Access

set

Default Value

ReportFile1.txt

Units

N/A

Interfaces

GUI, script

LeftJustify

When the LeftJustify field is set to On, then the data is left justified and appears at the left most side of the column. If the LeftJustify field is set to Off, then the data is centered in the column.

Data Type

Boolean

Allowed Values

On, Off

Access

set

Default Value

On

Units

N/A

Interfaces

GUI, script

Maximized

Allows the user to maximize the ReportFile window. This field cannot be modified in the Mission Sequence.

Data Type

Boolean

Allowed Values

true,false

Access

set

Default Value

false

Units

N/A

Interfaces

script

Precision

Allows the user to set the number of digits of the data written to a report.

Data Type

Integer

Allowed Values

Integer > 1

Access

set

Default Value

16

Units

Same as variable being reported

Interfaces

GUI, script

RelativeZOrder

Allows the user to select which ReportFile to display first on the screen. The ReportFile with lowest RelativeZOrder value will be displayed last while ReportFile with highest RelativeZOrder value will be displayed first. This field cannot be modified in the Mission Sequence.

Data Type

Integer

Allowed Values

Integer ≥ 0

Access

set

Default Value

0

Units

N/A

Interfaces

script

Size

Allows the user to control the display size of generated report file. First value in [0 0] matrix controls horizonal size and second value controls vertical size of report file window. This field cannot be modified in the Mission Sequence.

Data Type

Real array

Allowed Values

Any Real number

Access

set

Default Value

[ 0 0 ]

Units

N/A

Interfaces

script

SolverIterations

This field determines whether or not data associated with perturbed trajectories during a solver (Targeter, Optimize) sequence is written to a report file. When SolverIterations is set to All, all perturbations/iterations are written to a report file. When SolverIterations is set to Current, only current solution is written to a report file. When SolverIterations is set to None, this shows only final solution after the end of an iterative process and reports only final solution to a report file.

Data Type

Enumeration

Allowed Values

All, Current, None

Access

set

Default Value

Current

Units

N/A

Interfaces

GUI, script

Upperleft

Allows the user to pan the generated report file display window in any direction. First value in [0 0] matrix helps to pan the report file window horizontally and second value helps to pan the window vertically. This field cannot be modified in the Mission Sequence.

Data Type

Real array

Allowed Values

Any Real number

Access

set

Default Value

[ 0 0 ]

Units

N/A

Interfaces

script

WriteHeaders

This field specifies whether to include headers that describe the variables in a report file.

Data Type

Boolean

Allowed Values

True, False

Access

set

Default Value

True

Units

N/A

Interfaces

GUI, script

WriteReport

This field specifies whether to write data to the report FileName.

Data Type

Boolean

Allowed Values

True, False

Access

set

Default Value

True

Units

N/A

Interfaces

GUI, script

ZeroFill

Allows zeros to be placed in data written to a report to match set precision.

Data Type

Boolean

Allowed Values

On, Off

Access

set

Default Value

Off

Units

N/A

Interfaces

GUI, script

GUI

Figure below shows default name and settings for the ReportFile resource:

Remarks

Behavior When using Filename field

GMAT allows you to specify the name of the report file in two ways. The default naming convention for a report file when using FileName field is shown below:

Create ReportFile aReport
aReport.Filename = 'ReportFile1.txt'
aReport.WriteReport = true

An alternate method for naming a report file is to name the file without using any single quotes around the report file’s name.

Create ReportFile aReport
aReport.Filename = ReportFile1.txt
aReport.WriteReport = true

How data is reported to a report file

GMAT allows you to report data to a report file in two ways: You can use ReportFile.Add field or a Report command.

You can add data using the .Add field of ReportFile resource and this method reports data to the report file at each propagation step. Below is an example script snippet that shows how to report epoch and selected orbital elements using the .Add field:

Create Spacecraft aSat
Create ReportFile aReport

aReport.Add = {aSat.UTCGregorian aSat.Earth.SMA, aSat.Earth.ECC, ...
aSat.Earth.TA, aSat.EarthMJ2000Eq.RAAN}

Create Propagator aProp

BeginMissionSequence
Propagate aProp(aSat) {aSat.ElapsedSecs = 8640.0}

GMAT’s ReportFile.Add field will not report selected data to the report file at each propagation step if Propagate command is not included under the BeginMissionSequence.

An alternative method of reporting data to the report file is via the Report command. Using the Report command allows you to report data to the report file at specific points in your mission. Below is an example script snippet that shows how to report epoch and selected orbital elements using the Report command:

Create Spacecraft aSat
Create ReportFile aReport

Create Propagator aProp

BeginMissionSequence

Report aReport aSat.UTCGregorian aSat.Earth.SMA aSat.Earth.ECC ...
aSat.Earth.TA aSat.EarthMJ2000Eq.RAAN

Propagate aProp(aSat) {aSat.ElapsedSecs = 8640.0}

Report aReport aSat.UTCGregorian aSat.Earth.SMA aSat.Earth.ECC ...
aSat.Earth.TA aSat.EarthMJ2000Eq.RAAN

Behavior and Interactions when using ReportFile Resource & Report Command

Suppose you utilize a ReportFile resource and opt not to write a report and select false for the field name WriteReport, as shown in the example below:

Create ReportFile aReport
aReport.Filename = ReportFile1.txt
aReport.Add = {aSat.A1ModJulian, aSat.Earth.SMA}
aReport.WriteReport = false

Now assume that at the same time, you decide to utilize Report command in the Mission tree, as shown in the example script snippet below:

BeginMissionSequence;
Report aReport aSat.A1ModJulian aSat.Earth.SMA aSat.Earth.ECC
Propagate aProp(aSat) {aSat.Earth.Periapsis}
Report aReport aSat.A1ModJulian aSat.Earth.SMA aSat.Earth.ECC

At this point, you may think that since false option is selected under the field name WriteReport in ReportFile resource, hence GMAT will not generate the report file called ReportFile1.txt. On the Contrary, GMAT will generate a report called ReportFile1.txt, but this report will only contain data that was requested using the Report command. ReportFile1.txt text file will contain epoch, semi-major-axis and eccentricity only at specific points of the mission.

Behavior when reporting data in Iterative Processes

GMAT allows you to specify how data is written to reports during iterative processes such as differential correction or optimization. SolverIterations field of ReportFile resource supports 3 options which are described in the table below:

SolverIterations optionsDescription
All

Shows only current iteration/perturbation after the end of an iterative process and reports current solution to a report file.

Current

Shows all iterations/perturbations in an iterative process and reports all iterations/perturbations to a report file.

None

Shows only final solution after the end of an iterative process and reports only final solution to a report file.

Where Reports are written

GMAT allows you to write reports to any desired path or location. You can do this by going to GMAT’s startup file called gmat_startup_file.txt and define an absolute path under OUTPUT_PATH. This allows you to save report files in the directory of your choice as oppose to saving report files in GMAT's default Output folder. In ReportFile.FileName field, If no path is provided and only name of the report file is defined, then report files are written to GMAT's default Output folder. The default path where reports are written to is the Output folder located in the main directory where GMAT is installed.

Below is an example script snippet that shows where generated reports are written when only report file’s name is provided under the FileName field. In this example, 'ReportFile1.txt'report is written to the Output folder located in the main directory where GMAT is installed:

Create ReportFile aReport

aReport.Filename = 'ReportFile1.txt'
aReport.Add = {aSat.A1ModJulian, aSat.Earth.ECC}

An alternate method where report files can be written is by defining a relative path. You can define the relative path in GMAT’s startup file gmat_startup_file.txt under OUTPUT_PATH. For example, you can set a relative path by setting OUTPUT_PATH = C:/Users/rqureshi/Desktop/GMAT/mytestfolder/../output2/. In this path, the syntax ".." means to “go up one level”. After saving the startup file, when the script is executed, the generated report file named under FileName field will be written to a path C:\Users\rqureshi\Desktop\GMAT\output2.

Another method where report files can be written to is by defining an absolute path in GMAT’s startup file gmat_startup_file.txt under OUTPUT_PATH. For example, you can set an absolute path by setting OUTPUT_PATH = C:/Users/rqureshi/Desktop/GMAT/mytestfolder/. When the script is executed, report file named under FileName field will be written to an absolute path C:\Users\rqureshi\Desktop\GMAT\mytestfolder.

Instead of defining a relative or an absolute path in GMAT's startup file, you can choose to define an absolute path under FileName field too. For example, if you set ReportFile.FileName = C:\Users\rqureshi\Desktop\GMAT\mytestfolder\ReportFile.txt, then report file will be saved in mytestfolder.

Behavior when using ReportFile Resource & Toggle Command

GMAT allows you to use Toggle command while using the Add field of ReportFile resource. When Toggle Off command is issued for a ReportFile, not data is sent to a report file until a Toggle On command is issued. Similarly, when a Toggle On command is used, data is sent to a report file at each integration step until a Toggle Off command is used.

Below is an example script snippet that shows how to use Toggle Off and Toggle On command while using the ReportFile resource. Spacecraft’s cartesian position vector is reported to the report file.

Create Spacecraft aSat
Create Propagator aProp

Create ReportFile aReport
aReport.Filename = 'ReportFile1.txt'
aReport.Add = {aSat.UTCGregorian, aSat.EarthMJ2000Eq.X ...
aSat.EarthMJ2000Eq.Y aSat.EarthMJ2000Eq.Z}

BeginMissionSequence

Toggle aReport Off
Propagate aProp(aSat) {aSat.ElapsedDays = 2}
Toggle aReport On
Propagate aProp(aSat) {aSat.ElapsedDays = 4}

Behavior When Specifying Empty Brackets in ReportFile's Add Field

When using ReportFile.Add field, GMAT does not allow brackets to be left empty. The brackets must always be populated with values that you wish to report. If brackets are left empty, then GMAT throws in an exception. Below is a sample script snippet that shows an example of empty brackets. If you were to run this script, then GMAT throws in an execption reminding you that brackets cannot be left empty.

Create Spacecraft aSat
Create Propagator aProp
Create ReportFile aReport

aReport.Add = {}

BeginMissionSequence
Propagate aProp(aSat) {aSat.ElapsedSecs = 8640.0}

Examples

Propagate an orbit and write cartesian state to a report file at every integrator step

Create Spacecraft aSat
Create Propagator aProp

Create ReportFile aReport
GMAT aReport.Filename = 'ReportFile1.txt'
aReport.Add = {aSat.EarthMJ2000Eq.X aSat.EarthMJ2000Eq.Y ...
aSat.EarthMJ2000Eq.Z aSat.EarthMJ2000Eq.VX ...
aSat.EarthMJ2000Eq.VY aSat.EarthMJ2000Eq.VZ}

BeginMissionSequence

Propagate aProp(aSat) {aSat.ElapsedSecs = 8640.0}

Propagate an orbit for 1 day and write cartesian state to a report file at specific points in your mission

Create Spacecraft aSat
Create Propagator aProp

Create ReportFile aReport
GMAT aReport.Filename = 'ReportFile1.txt'

BeginMissionSequence

Report aReport aSat.EarthMJ2000Eq.X aSat.EarthMJ2000Eq.Y ...
aSat.EarthMJ2000Eq.Z aSat.EarthMJ2000Eq.VX ...
aSat.EarthMJ2000Eq.VY aSat.EarthMJ2000Eq.VZ

Propagate aProp(aSat) {aSat.ElapsedDays = 1}

Report aReport aSat.EarthMJ2000Eq.X aSat.EarthMJ2000Eq.Y ...
aSat.EarthMJ2000Eq.Z aSat.EarthMJ2000Eq.VX ...
aSat.EarthMJ2000Eq.VY aSat.EarthMJ2000Eq.VZ

SolarSystem

SolarSystem — High level solar system configuration options

Description

The SolarSystem resource allows you to define global properties for the model of the solar system including the ephemeris source for built-in celestial bodies and selected settings to improve performance when medium fidelity modelling is acceptable for your application. This resource cannot be modified in the Mission Sequence.

See Also: CelestialBody, LibrationPoint, Barycenter, CoordinateSystem

Fields

FieldDescription
DEFilename

The path and name of the DE file.

Data Type

String

Allowed Values

Valid DE file

Access

set

Default Value

../data/planetary_ephem/de/leDE1941.405

Units

N/A

Interfaces

GUI, script

EphemerisSource

The ephemeris model for built-in celestial bodies.

Data Type

String

Allowed Values

DE405, DE421, DE424, or SPICE

Access

set

Default Value

DE405

Units

N/A

Interfaces

GUI, script

EphemerisUpdateInterval

The time between time updates for celetial body ephemeris. For example, if EphemerisUpdateInterval = 60, if an ephemeris call is made at time t = 1200, and a subsequent call is made at time t = 1210, the same ephemeris will be returned for the second call. This option is for high speed, low fidelity modelling or for use when modelling orbits far from third body perturbation sources.

Data Type

Real

Allowed Values

Real >= 0

Access

set

Default Value

0

Units

N/A

Interfaces

GUI, script

LSKFilename

The path and name of the SPK leap second kernel.

Data Type

String

Allowed Values

Valid SPK leapsecond kernel

Access

set

Default Value

../data/time/naif0010.tls

Units

N/A

Interfaces

GUI, script

SPKFilename

The path and name of the SPK orbit ephemeris kernel.

Data Type

String

Allowed Values

Valid SPK ephemeris kernel (.bsp)

Access

set

Default Value

../data/planetary_ephem/spk/DE421AllPlanets.bsp

Units

N/A

Interfaces

GUI, script

UseTTForEphemeris

Flag to use Terrestrial Time (TT) as input to the orbital ephemeris routines. When set to false, TDB is used.

Data Type

String

Allowed Values

true,false

Access

set

Default Value

false

Units

N/A

Interfaces

GUI, script

GUI

The SolarSystem dialog box allows you to configure global properties for solar system modelling and the default configuration is illustrated above. Use EphemerisSource to choose the ephemeris model for built-in celestial bodies. If you select either DE405, DE421, or DE424 the dialog box above illustrates available options.

Warning

Caution: GMAT allows you to provide user-created DE or SPK kernel files but we recommend using the files distributed with GMAT. The files provided with GMAT have been extensively tested for consistency and accuracy with the original data provided by JPL and other models in GMAT. Using inconsistent ephemeris files or user-generated files can result in instability or numerical issues if the files are not generated correctly.

Changing the ephemeris source for an application is equivalent to making a fundamental change to the model of the solar system. We recommend selecting the EphemerisSource early in the analysis process and using that model consistently. In the event that an ephemeris model change is necessary, we recommend that you change the model in the script file and not via the GUI. We allow you to change EphemerisSource via the GUI for convenience in early design phases when rigorous consistency in modelling is less important.

If you select SPICE for EphemerisSource, the SolarSystem dialog box reconfigures to allow you to define the SPK Kernel and the leap second kernel.

Remarks

GMAT uses the ephemeris file selected in the EphemerisSource field for all built-in celestial bodies. For user-defined bodies, the ephemeris model is specified on the CelestialBody object.

  • For more information on the DE files provided by JPL see here.

  • For general information on SPICE ephemeris files see the JPL NAIF site.

  • For information on the SPK kernel named DE421AllPlanets.bsp distributed with GMAT see the SPK.Readme located in \data\planetary_ephem\spk in the GMAT distribution.

Note: The SolarSystem and built-in CelestialBody resources require several hundred fields for full configuration. GMAT only saves non-default values for SolarSystem and CelestialBody to the script so that scripts are not populated with hundreds of default settings.

Examples

Use DE421 for ephemeris.

GMAT SolarSystem.EphemerisSource = 'DE421'

Create Spacecraft aSpacecraft
Create Propagator aPropagator
aPropagator.FM = aForceModel
Create ForceModel aForceModel
aForceModel.PointMasses = {Luna, Sun}

BeginMissionSequence

Propagate aPropagator(aSpacecraft) {aSpacecraft.ElapsedSecs = 12000.0}

Use SPICE for ephemeris.

GMAT SolarSystem.EphemerisSource = 'SPICE'

Create Spacecraft aSpacecraft
Create Propagator aPropagator
aPropagator.FM = aForceModel
Create ForceModel aForceModel
aForceModel.PointMasses = {Luna, Sun}

BeginMissionSequence

Propagate aPropagator(aSpacecraft) {aSpacecraft.ElapsedSecs = 12000.0}      

Spacecraft

Spacecraft — A spacecraft model

Description

A Spacecraft resource is GMAT's spacecraft model and includes data and models for the spacecraft's orbit, epoch, attitude, and physical parameters (such as mass and drag coefficient), as well as attached hardware, including tanks and thrusters. The Spacecraft model also contains the data that configures how the Spacecraft 3-D CAD model is used in an OrbitView. Spacecraft has certain fields that can be set in the Mission Sequence and some that cannot. See the field tables on the pages below for more information.

GMAT's documentation for Spacecraft is extensive and is broken down into the following sections:


Spacecraft Attitude

Spacecraft Attitude — The spacecraft attitude model

Description

GMAT models the orientation and rate of rotation of a spacecraft using several different mathematical models. Currently, GMAT assumes that a Spacecraft is a rigid body. The currently supported attitude models are Spinner, CoordinateSystemFixed, and SpiceAttitude. The Spinner model is a simple, inertially fixed spin axis model. The CoordinateSystemFixed model allows you to use any CoordinateSystem supported by GMAT as the attitude of a Spacecraft. The SpiceAttitude model allows you to define the Spacecraft attitude based on SPICE attitude kernels.

See Also: Spacecraft

Fields

FieldDescription
AngularVelocityX

The x-component of Spacecraft body angular velocity expressed in the inertial frame. AngularVelocityX is used for the following Attitude models: Spinner.

Data Type

Real

Allowed Values

-∞ < Real< ∞

Access

set,get

Default Value

0

Units

deg/sec

Interfaces

GUI, script

AngularVelocityY

The y-component of Spacecraft body angular velocity expressed in the inertial frame. AngularVelocityY is used for the following Attitude models: Spinner.

Data Type

Real

Allowed Values

-∞ < Real< ∞

Access

set,get

Default Value

0

Units

deg/sec

Interfaces

GUI, script

AngularVelocityZ

The z-component of Spacecraft body angular velocity expressed in the inertial frame. AngularVelocityZ is used for the following Attitude models: Spinner.

Data Type

Real

Allowed Values

-∞ < Real< ∞

Access

set,get

Default Value

0

Units

deg/sec

Interfaces

GUI, script

Attitude

The attitude mode for the Spacecraft.

Data Type

String

Allowed Values

CoordinateSystemFixed, Spinner, SpiceAttitude

Access

set

Default Value

CoordinateSystemFixed

Units

N/A

Interfaces

GUI, script

AttitudeCoordinateSystem

The CoordinateSystem used in attitude computations. The AttitudeCoordinateSystem field is only used for the following attitude models: CoordinateSystemFixed.

Data Type

String

Allowed Values

CoordinateSystem resource.

Access

set

Default Value

EarthMJ2000Eq

Units

N/A

Interfaces

GUI, script

AttitudeRate-DisplayStateType

The attitude rate representation to display in the GUI and script file. AttitudeRateDisplayType is used for the following attitude models: Spinner.

Data Type

String

Allowed Values

AngularVelocity, EulerAngleRates

Access

set

Default Value

AngularVelocity

Units

N/A

Interfaces

GUI, script

AttitudeSpiceKernelName

SPK Kernels for Spacecraft attitude. SPK atttitude kernels have extension ".BC". This field cannot be set in the Mission Sequence.

Data Type

String array

Allowed Values

Array of attitude kernel files

Access

set

Default Value

empty array

Units

N/A

Interfaces

GUI, script

DCM11

Component (1,1) of the Direction Cosine Matrix. DCM11 is used for the following Attitude models: Spinner.

Data Type

Real

Allowed Values

-1 <= Real <=1

Access

set,get

Default Value

1

Units

N/A

Interfaces

GUI, script

DCM12

Component (1,2) of the Direction Cosine Matrix. DCM12 is used for the following Attitude models: Spinner.

Data Type

Real

Allowed Values

-1 <= Real <=1

Access

set,get

Default Value

0

Units

N/A

Interfaces

GUI, script

DCM13

Component (1,3) of the Direction Cosine Matrix. DCM13 is used for the following Attitude models: Spinner.

Data Type

Real

Allowed Values

-1 <= Real <=1

Access

set,get

Default Value

0

Units

N/A

Interfaces

GUI, script

DCM21

Component (2,1) of the Direction Cosine Matrix. DCM21 is used for the following Attitude models: Spinner.

Data Type

Real

Allowed Values

-1 <= Real <=1

Access

set,get

Default Value

0

Units

N/A

Interfaces

GUI, script

DCM22

Component (2,2) of the Direction Cosine Matrix. DCM22 is used for the following Attitude models: Spinner.

Data Type

Real

Allowed Values

-1 <= Real <=1

Access

set,get

Default Value

1

Units

N/A

Interfaces

GUI, script

DCM23

Component (2,3) of the Direction Cosine Matrix. DCM23 is used for the following Attitude models: Spinner.

Data Type

Real

Allowed Values

-1 <= Real <=1

Access

set,get

Default Value

0

Units

N/A

Interfaces

GUI, script

DCM31

Component (3,1) of the Direction Cosine Matrix. DCM31 is used for the following Attitude models: Spinner.

Data Type

Real

Allowed Values

-1 <= Real <=1

Access

set,get

Default Value

0

Units

N/A

Interfaces

GUI, script

DCM32

Component (3,2) of the Direction Cosine Matrix. DCM32 is used for the following Attitude models: Spinner.

Data Type

Real

Allowed Values

-1 <= Real <=1

Access

set,get

Default Value

1

Units

N/A

Interfaces

GUI, script

DCM33

Component (3,3) of the Direction Cosine Matrix. DCM33 is used for the following Attitude models: Spinner.

Data Type

Real

Allowed Values

-1 <= Real <=1

Access

set,get

Default Value

1

Units

N/A

Interfaces

GUI, script

EulerAngle1

The value of the first Euler angle. EulerAngle1 is used for the following Attitude models: Spinner.

Data Type

Real

Allowed Values

-∞ < Real < ∞

Access

set,get

Default Value

0

Units

deg.

Interfaces

GUI, script

EulerAngle2

The value of the second Euler angle. EulerAngle2 is used for the following Attitude models: Spinner.

Data Type

Real

Allowed Values

-∞ < Real < ∞

Access

set,get

Default Value

0

Units

deg.

Interfaces

GUI, script

EulerAngle3

The value of the third Euler angle. EulerAngle3 is used for the following Attitude models: Spinner.

Data Type

Real

Allowed Values

-∞ < Real < ∞

Access

set,get

Default Value

0

Units

deg.

Interfaces

GUI, script

EulerAngleRate1

The value of the first Euler angle rate. EulerAngleRate1 is used for the following Attitude models: Spinner.

Data Type

Real

Allowed Values

-∞ < Real < ∞

Access

set,get

Default Value

0

Units

deg./sec.

Interfaces

GUI, script

EulerAngleRate2

The value of the second Euler angle rate. EulerAngleRate2 is used for the following Attitude models: Spinner.

Data Type

Real

Allowed Values

-∞ < Real < ∞

Access

set,get

Default Value

1

Units

deg./sec.

Interfaces

GUI, script

EulerAngleRate3

The value of the third Euler angle rate. EulerAngleRate3 is used for the following Attitude models: Spinner.

Data Type

Real

Allowed Values

-∞ < Real < ∞

Access

set,get

Default Value

1

Units

deg./sec.

Interfaces

GUI, script

FrameSpiceKernelName

SPK Kernels for Spacecraft body frame. SPK Frame kernels have extension ".TF". This field cannot be set in the Mission Sequence.

Data Type

String array

Allowed Values

Array of .tf files.

Access

set

Default Value

emtpy array

Units

N/A

Interfaces

GUI, script

EulerAngleSequence

The Euler angle sequence used for Euler angle input and output..

Data Type

String

Allowed Values

123,231,312,132,321,213,121, 232,313,131,323,212

Access

set

Default Value

321

Units

N/A

Interfaces

GUI, script

MRP1

The value of the first modified Rodrigues parameter. MRP1 is used for the following Attitude models: Spinner.

Data Type

Real

Allowed Values

-∞ < Real < ∞

Access

set,get

Default Value

0

Units

dimensionless

Interfaces

GUI, script

MRP2

The value of the second modified Rodrigues parameter. MRP2 is used for the following Attitude models: Spinner.

Data Type

Real

Allowed Values

-∞ < Real < ∞

Access

set,get

Default Value

0

Units

dimensionless

Interfaces

GUI, script

MRP3

The value of the second modified Rodrigues parameter. MRP2 is used for the following Attitude models: Spinner.

Data Type

Real

Allowed Values

-∞ < Real < ∞

Access

set,get

Default Value

0

Units

dimensionless

Interfaces

GUI, script

Q1

First component of quaternion. GMAT’s quaternion representation includes the three “vector” components as the first three elements in the quaternion and the “rotation” component as the last element in the quaternion. Q1 is used for the following Attitude models: Spinner.

Data Type

Real

Allowed Values

-∞ < Real < ∞

Access

set,get

Default Value

0

Units

dimensionless

Interfaces

GUI, script

Q2

Second component of quaternion. GMAT’s quaternion representation includes the three “vector” components as the first three elements in the quaternion and the “rotation” component as the last element in the quaternion. Q2 is used for the following Attitude models: Spinner.

Data Type

Real

Allowed Values

-∞ < Real < ∞

Access

set,get

Default Value

0

Units

dimensionless

Interfaces

GUI, script

Q3

Third component of quaternion. GMAT’s quaternion representation includes the three “vector” components as the first three elements in the quaternion and the “rotation” component as the last element in the quaternion. Q3 is used for the following Attitude models: Spinner.

Data Type

Real

Allowed Values

-∞ < Real < ∞

Access

set,get

Default Value

0

Units

dimensionless

Interfaces

GUI, script

Q4

Fourth component of quaternion. GMAT’s quaternion representation includes the three “vector” components as the first three elements in the quaternion and the “rotation” component as the last element in the quaternion. Q4 is used for the following Attitude models: Spinner.

Data Type

Real

Allowed Values

-∞ < Real < ∞

Access

set,get

Default Value

1

Units

dimensionless

Interfaces

GUI, script

Quaternion

The quaternion vector. GMAT’s quaternion representation includes the three “vector” components as the first three elements in the quaternion and the “rotation” component as the last element in the quaternion. Quaternion is used for the following Attitude models: Spinner.

Data Type

Real array

Allowed Values

Real array (length four)

Access

set,get

Default Value

[0 0 0 1];

Units

dimensionless

Interfaces

GUI, script

SCClockSpiceKernelName

SPK Kernels for spacecraft clock. SPK clock kernels have extension ".TSC". This field cannot be set in the Mission Sequence.

Data Type

String array

Allowed Values

Array of .tsc file names

Access

set,get

Default Value

empty array

Units

N/A

Interfaces

GUI, script

Remarks

Overview of Availble Attitude Models

GMAT models the orientation and rate of rotation of a Spacecraft using several different mathematical models. Different attitude models require different information to fully configure the model. For example, when you select the CoordinateSystemFixed model, the attitude and body rates are entirely determined by the CoordinateSystem model and defining Euler angles or angular velocity components are not required and have no effect. The table below describes which interface elements such as the AttitudeCoordinateSystem, attitude representation, attitude rate fields among others are required/supported for a given model. Attitude representations fields include the DCM, EulerAngles, Quaternion, and MRPs (Modified Rodriguez Parameters). Attitude rate fields include the body angular velocity and the Euler angle rates. If a field is marked as inactive for a particular model, fields of that type have no effect for that model. Similarly, fields marked as active do affect the attitude for a particular model.

Attitude ModelCoord. Sys.Attitude RepressentationAttitude RateEuler Sequence
Spinner

Inactive

Active

Active

Active

Coordinate-SystemFixed

Active

Inactive

Inactive

Active

SpiceAttitude

Inactive

Inactive

Inactive

Active

Overview of State Representations

Quaternion

The quaternion is a four element, non-singular attitude representation. GMAT’s quaternion representation includes the three “vector” components as the first three elements in the quaternion and the “rotation” component as the last element in the quaternion. In assignment mode, you can set the quaternions element by element like this

aSpacecraft.Q1 = 0.5
aSpacecraft.Q2 = 0.5
aSpacecraft.Q3 = 0.5
aSpacecraft.Q4 = 0.5                

or simultaneously set the entire quaternion like this

aSpacecraft.Quaternion = [0.5 0.5 0.5 0.5]         

GMAT normalizes the quaternion before use. In command mode, you must enter the entire quaternion as a single vector to avoid scaling components of the quaternion before the entire quaternion is set.

DirectionCosineMatrix (DCM)

The Direction Cosine Matrix is a 3x3 array that contains cosines of the angles between the x, y, and z body axes and the x, y, and z inertial axes. The direction cosine matrix must be ortho-normal and you define the DCM element by element. Here is an example that shows how to define the attitude using the DCM.

aSpacecraft.DCM11 = 1
aSpacecraft.DCM12 = 0
aSpacecraft.DCM13 = 0
aSpacecraft.DCM21 = 0
aSpacecraft.DCM22 = 1
aSpacecraft.DCM23 = 0
aSpacecraft.DCM31 = 0
aSpacecraft.DCM32 = 0
aSpacecraft.DCM33 = 1        

Euler Angles

Euler angles are a sequence of three rotations about coordinate axes to transform from one system to another system. GMAT supports all 12 Euler angle sequences. Here is an example setting attitude using a “321” sequence.

aSpacecraft.EulerAngleSequence = '321'
aSpacecraft.EulerAngle1 = 45
aSpacecraft.EulerAngle2 = 45
aSpacecraft.EulerAngle3 = 90      

Warning

Caution: The Euler angles have singularities that can cause issues during modeling. We recommend using other representations for this reason.

Modified Rogriques parameters

The modified Rodgriques parameters are a modification of the Euer Axis/Angle representation. Specifically, the MRP vector is equal to nhat* tan(Euler Angle/4) where nhat is the unitized Euler Axis.

aSpacecraft.MRP1 = 0.2928932188134525
aSpacecraft.MRP2 = 0.2928932188134524
aSpacecraft.MRP3 = 1.149673585146546e-017

Euler Angles Rates

The Euler angle rates are the first time derivative of the Euler angles and can be used to define the body rates. Euler angle rates use the same sequence as the EulerAngles. The example below shows how to define the Euler angle rates for a spacecraft.

aSpacecraft.EulerAngleSequence = '321'
aSpacecraft.EulerAngleRate1 = -5
aSpacecraft.EulerAngleRate2 = 20
aSpacecraft.EulerAngleRate3 = 30      

Angular Velocity

The angular velocity is the angular velocity of the spacecraft body with respect to the inertial frame, expressed in the inertial frame. The example below shows how to define the angular velocity for a spacecraft.

aSpacecraft.AngularVelocityX = 5;
aSpacecraft.AngularVelocityY = 10;
aSpacecraft.AngularVelocityZ = 5;

Coordinate System Fixed Attitude Model

The CoordinateSystemFixed model allows you to use any existing CoordinateSystem to define the attitude of a Spacecraft. The attitude uses the axes defined on the CoordinateSystem to compute the body fixed to inertial matrix and attitude rate parameters such as the angular velocity. To configure this attitude mode, select CoordinateSystemFixed, for Attitude. You can define the EulerAngleSequence used when outputting EulerAngles and EulerAngle rates.

Warning

For the CoordinateSystemFixed attitude model, the attitude is completely described by the selected coordinate system. If you are working in the script, setting attitude parameters (Euler Angles, Quaternion etc.) or setting attitude rate parameters such as (Euler Angle Rates etc.) has no effect.

The script example below shows how to configure a Spacecraft to use a spacecraft VNB attitude system.

Create Spacecraft aSat
aSat.Attitude                 = CoordinateSystemFixed
aSat.ModelRotationZ           = -90
aSat.AttitudeCoordinateSystem = 'attCoordSys'

Create ForceModel Propagator1_ForceModel
Create Propagator Propagator1
Propagator1.FM        = Propagator1_ForceModel
Propagator1.MaxStep   = 10

Create CoordinateSystem attCoordSys
attCoordSys.Origin    = Earth
attCoordSys.Axes      = ObjectReferenced
attCoordSys.XAxis     = V
attCoordSys.YAxis     = N
attCoordSys.Primary   = Earth
attCoordSys.Secondary = aSat

Create OrbitView OrbitView1;
OrbitView1.Add                = {aSat, Earth}
OrbitView1.ViewPointReference = Earth
OrbitView1.ViewPointVector    = [ 30000 0 0 ]

BeginMissionSequence

Propagate Propagator1(aSat) {aSat.ElapsedSecs = 12000.0}

Spinner Attitude Model

The Spinner attitude model propagates the attitude assuming the spin axis direction is fixed in inertial space. You define the attitude by providing initial body orientation and rates. GMAT propagates the attitude by computing the angular velocity and then rotates the Spacecraft about that angular velocity vector at a constant rate defined by the magnitude of the angular velocity. You can define the initial attitude using quaternions, Euler angles, the DCM, or the modified Rodriques parameters. You can define the attitude rates using Euler angles rates or angular velocity. When working with Euler angles, the rotation sequence is determined by the EulerAngleSequence field.

Warning

Caution: If you are working in the script, setting the CoordinateSystem for the Spinner attitude model has no effect.

The example below configures a spacecraft to spin about the inertial z axis.

Create Spacecraft aSat;
aSat.Attitude         = Spinner
aSat.ModelRotationZ   = -90
aSat.AngularVelocityZ = 5

Create ForceModel Propagator1_ForceModel
Create Propagator Propagator1
GMAT Propagator1.FM        = Propagator1_ForceModel
GMAT Propagator1.MaxStep   = 10

Create CoordinateSystem attCoordSys
attCoordSys.Origin    = Earth
attCoordSys.Axes      = ObjectReferenced
attCoordSys.XAxis     = V
attCoordSys.YAxis     = N
attCoordSys.Primary   = Earth
attCoordSys.Secondary = aSat

Create OrbitView OrbitView1;
OrbitView1.Add                = {aSat, Earth}
OrbitView1.ViewPointReference = Earth
OrbitView1.ViewPointVector    = [ 30000 0 0 ]

BeginMissionSequence

Propagate Propagator1(aSat) {aSat.ElapsedSecs = 12000.0}

SPK Attitude Model

The SpiceAttitude model propagates the attitude using attitude SPICE kernels. To configure a Spacecraft to use SPICE kernels select SpiceAttitude for the Attitude field as shown below.

Warning

Caution: For the SpiceAttitude model, the attitude is completely described by the spice kernels. When working in the script, setting the CoordinateSystem, attitude parameters (EulerAngles, Quaternion etc.) or attitude rate parameters such as (EulerAngleRates etc.) has no effect.

You must provide three SPICE kernel types for the SpiceAttitude model: the attitude kernel (.bc file), the frame kernel (.tf file) and the spacecraft clock kernel (.tsc file). These files are defined on the Spacecraft SPICE tab as shown below. In addition to the kernels, you must also provide the Spacecraft NAIFId and the NAIFIdReferenceFrame. Below is an illustration of the SPICE tab configured for MarsExpress script found later in this section.

The example below configures a Spacecraft to use SPK kernels to propagator the attitude for Mars Express. The SPK kernels are distributed with GMAT.

Create Spacecraft MarsExpress
MarsExpress.NAIFId = -41
MarsExpress.NAIFIdReferenceFrame = -41001
MarsExpress.Attitude = 'SpiceAttitude'
MarsExpress.OrbitSpiceKernelName = ...
{'../data/vehicle/ephem/spk/MarsExpress_Short.BSP'}
MarsExpress.AttitudeSpiceKernelName = ...
{'../data/vehicle/ephem/spk/MarsExpress_ATNM_PTR00012_100531_002.BC'}
MarsExpress.SCClockSpiceKernelName = ...
{'../data/vehicle/ephem/spk/MarsExpress_MEX_100921_STEP.TSC'}
MarsExpress.FrameSpiceKernelName = ...
{'../data/vehicle/ephem/spk/MarsExpress_MEX_V10.TF'}

Create Propagator spkProp
spkProp.Type = SPK
spkProp.StepSize = 60
spkProp.CentralBody = Mars
spkProp.EpochFormat = 'UTCGregorian'
spkProp.StartEpoch = '01 Jun 2010 16:59:09.815'

Create CoordinateSystem MarsMJ2000Eq
MarsMJ2000Eq.Origin = Mars
MarsMJ2000Eq.Axes = MJ2000Eq

Create OrbitView Enhanced3DView1
Enhanced3DView1.Add = {MarsExpress, Mars}
Enhanced3DView1.CoordinateSystem = MarsMJ2000Eq
Enhanced3DView1.ViewPointReference = Mars
Enhanced3DView1.ViewPointVector = [ 10000 10000 10000 ]
Enhanced3DView1.ViewDirection = Mars

BeginMissionSequence

Propagate spkProp(MarsExpress) {MarsExpress.ElapsedDays = 0.2}

Spacecraft Ballistic/Mass Properties

Spacecraft Ballistic/Mass Properties — The physical properties of the spacecraft

Description

The Spacecraft ballistic and mass properties include the drag and SRP areas and coefficients as well as the spacecraft dry mass. These quantities are used primarily in orbital dynamics modelling.

See Also: Propagate, Propagator,Spacecraft

Fields

FieldDescription
Cd

The coefficent of drag used to compute the acceleration due to drag.

Data Type

Real

Allowed Values

Real >= 0

Access

set, get

Default Value

2.2

Units

dimensionless

Interfaces

GUI, script

Cr

The coefficent of reflectivity used to compute the acceleration due toSRP.

Data Type

Real

Allowed Values

0 <= Cr <= 2.0

Access

set, get

Default Value

1.8

Units

dimensionless

Interfaces

GUI, script

Drag Area

The area used to compute acceleration due to atmospheric drag.

Data Type

Real

Allowed Values

Real > = 0

Access

set, get

Default Value

15

Units

m^2

Interfaces

GUI, script

DryMass

The dry mass of the Spacecraft (does not include fuel mass).

Data Type

Real

Allowed Values

Real >=0

Access

set, get

Default Value

850

Units

kg

Interfaces

GUI, script

SRPArea

The area used to compute acceleration due to solar radiation pressure.

Data Type

Real

Allowed Values

Real > 0

Access

set, get

Default Value

1

Units

m^2

Interfaces

GUI, script

GUI

The GUI interface for ballistic and mass properties is contained on the Ballistic/Mass tab of the Spacecraft resource. You can enter physical properties such as the drag and SRP areas and coefficients and the Spacecraft dry mass which are used in orbital dynamics modelling.

Remarks

Configuring Ballistic and Mass Properties

GMAT uses a cannonball model for drag and SRP. In the cannonball model, the area is assumed to be independent of the spacecraft’s orientation with respect to the local velocity vector and the sun vector. For more details on the computation and configuration of drag and SRP models see the Force Model documentation.

Total Mass Computation

The TotalMass property of a Spacecraft is a read-only property that is the sum of the DryMass value and the sum of the fuel mass in all attached fuel tanks. GMAT’s propagators will not allow the total mass of a spacecraft to be negative. However, GMAT will allow the mass of a FuelTank to be negative. See the FuelTank documentation for details.

Examples

Configure physical properties.

Create Spacecraft aSpacecraft
aSpacecraft.Cd        = 2.2
aSpacecraft.Cr        = 1.8
aSpacecraft.DragArea  = 40
aSpacecraft.SRPArea   = 35
aSpacecraft.DryMass   = 2000
Create Propagator aPropagator

BeginMissionSequence

Propagate   aPropagator(aSpacecraft, {aSpacecraft.ElapsedSecs = 600})

Spacecraft Epoch

Spacecraft Epoch — The spacecraft epoch

Description

The epoch of a Spacecraft is the time and date corresponding to the specified orbit state. See the Spacecraft Orbit State section for interactions between the epoch, coordinate system, and spacecraft state fields.

See Also: Spacecraft

Caution

GMAT’s Modified Julian Date (MJD) format differs from that of other software. The Modified Julian format is a constant offset from the full Julian date (JD):

MJD = JD - offset

GMAT uses a non-standard offset, as shown in the following table.

Epoch TypeGMATcommon
reference epoch05 Jan 1941 12:00:00.00017 Nov 1858 00:00:00.000
Modified Julian offset2430000.02400000.5

Fields

FieldDescription
DateFormat

The time system and format of the Epoch field. In the GUI, this field is called EpochFormat.

Data Type

Enumeration

Allowed Values

A1ModJulian, TAIModJulian, UTCModJulian, TTModJulian, TDBModJulian, A1Gregorian, TAIGregorian, TTGregorian, UTCGregorian, TDBGregorian

Access

set only

Default Value

TAIModJulian

Interfaces

GUI, script

Epoch

The time and date corresponding to the specified orbit state.

Data Type

Time

Allowed Values

Gregorian: 04 Oct 1957 12:00:00.000 <= Epoch <= 28 Feb 2100 00:00:00.000

Modified Julian: 6116.0 <= Epoch <= 58127.5

Access

set only

Default Value

21545

Interfaces

GUI, script

A1ModJulian

The Spacecraft orbit epoch in the A.1 system and the Modified Julian format.

Data Type

String

Allowed Values

See Epoch

Access

set, get (mission sequence only)

Default Value

21545.00000039794

Units

Days

Interfaces

script

Epoch.A1ModJulian

The spacecraft orbit epoch in the A.1 system and the Modified Julian format.

Data Type

String

Allowed Values

See Epoch

Access

set, get

Default Value

21545.00000039794

Units

Days

Interfaces

none

CurrA1MJD

This field has been deprecated and should no longer be used.

The current epoch in the A1ModJulian format. This field can only be used within the mission sequence.

Data Type

Time

Allowed Values

6116.0 <= CurrA1MJD <= 58127.5

Access

get, set (mission sequence only)

Default Value

converted equivalent of 21545 Modified Julian (TAI)

Interfaces

script only

A1Gregorian

The Spacecraft orbit epoch in the A.1 system and the Gregorian format.

Data Type

String

Allowed Values

See Epoch

Access

set, get (mission sequence only)

Default Value

01 Jan 2000 12:00:00.034

Units

N/A

Interfaces

GUI, script

TAIGregorian

The Spacecraft orbit epoch in the TAI system and the Gregorian format.

Data Type

String

Allowed Values

See Epoch

Access

set, get (mission sequence only)

Default Value

01 Jan 2000 12:00:00.000

Units

Gregorian date

Interfaces

GUI, script

TAIModJulian

The Spacecraft orbit epoch in the TAI system and the Modified Julian format.

Data Type

String

Allowed Values

See Epoch

Access

set, get (mission sequence only)

Default Value

21545

Units

See A1ModJulian

Interfaces

GUI, script

TDBGregorian

The Spacecraft orbit epoch in the TDB system and the Gregorian format.

Data Type

String

Allowed Values

See Epoch

Access

set, get (mission sequence only)

Default Value

01 Jan 2000 12:00:32.184

Units

See A1Gregorian

Interfaces

GUI, script

TDBModJulian

The Spacecraft orbit epoch in the TDB system and the Modified Julian format.

Data Type

String

Allowed Values

See Epoch

Access

set, get (mission sequence only)

Default Value

21545.00037249916

Units

See A1ModJulian

Interfaces

GUI, script

TTGregorian

The Spacecraft orbit epoch in the TT system and the Gregorian format.

Data Type

String

Allowed Values

See Epoch

Access

set, get (mission sequence only)

Default Value

01 Jan 2000 12:00:32.184

Units

See A1Gregorian

Interfaces

GUI, script

TTModJulian

The Spacecraft orbit epoch in the TT system and the Modified Julian format.

Data Type

String

Allowed Values

See Epoch

Access

set, get (mission sequence only)

Default Value

21545.0003725

Units

See A1ModJulian

Interfaces

GUI, script

UTCGregorian

The Spacecraft orbit epoch in the UTC system and the Gregorian format.

Data Type

String

Allowed Values

See Epoch

Access

set, get (mission sequence only)

Default Value

01 Jan 2000 11:59:28.000

Units

See A1Gregorian

Interfaces

GUI, script

UTCModJulian

The Spacecraft orbit epoch in the UTC system and the Modified Julian format.

Data Type

String

Allowed Values

See Epoch

Access

set, get (mission sequence only)

Default Value

21544.99962962963

Units

See A1ModJulian

Interfaces

GUI, script

Epoch.A1Gregorian

The Spacecraft orbit epoch in the A.1 system and the Gregorian format.

Data Type

String

Allowed Values

See Epoch

Access

set, get

Default Value

01 Jan 2000 12:00:00.034

Units

N/A

Interfaces

GUI, script

Epoch.TAIGregorian

The Spacecraft orbit epoch in the TAI system and the Gregorian format.

Data Type

String

Allowed Values

See Epoch

Access

set, get

Default Value

DefaultValue

Units

01 Jan 2000 12:00:00.000

Interfaces

GUI, script

Epoch.TAIModJulian

The Spacecraft orbit epoch in the TAI system and the Modified Julian format.

Data Type

String

Allowed Values

See Epoch.A1ModJulian

Access

set, get

Default Value

21545

Units

See Epoch.A1ModJulian

Interfaces

GUI, script

Epoch.TDBGregorian

The Spacecraft orbit epoch in the TDB system and the Gregorian format.

Data Type

String

Allowed Values

See Epoch

Access

set, get

Default Value

01 Jan 2000 12:00:32.184

Units

See Epoch.A1Gregorian

Interfaces

GUI, script

Epoch.TDBModJulian

The Spacecraftorbit epoch in the TDB system and the Modified Julian format.

Data Type

String

Allowed Values

See Epoch

Access

set, get

Default Value

21545.00037249916

Units

See Epoch.A1ModJulian

Interfaces

GUI, script

Epoch.TTGregorian

The Spacecraft orbit epoch in the TT system and the Gregorian format.

Data Type

String

Allowed Values

See Epoch

Access

set, get

Default Value

01 Jan 2000 12:00:32.184

Units

See Epoch.A1Gregorian

Interfaces

GUI, script

Epoch.TTModJulian

The Spacecraftorbit epoch in the TT system and the Modified Julian format.

Data Type

String

Allowed Values

See Epoch

Access

set, get

Default Value

21545.0003725

Units

See Epoch.A1ModJulian

Interfaces

GUI, script

Epoch.UTCGregorian

The Spacecraftorbit epoch in the UTC system and the Gregorian format.

Data Type

String

Allowed Values

See Epoch

Access

set, get

Default Value

01 Jan 2000 11:59:28.000

Units

See Epoch.A1Gregorian

Interfaces

GUI, script

Epoch.UTCModJulian

The Spacecraft orbit epoch in the UTC system and the Modified Julian format.

Data Type

String

Allowed Values

Range

Access

See Epoch

Default Value

21544.99962962963

Units

See Epoch.A1ModJulian

Interfaces

GUI, script

GUI

A change in EpochFormat causes an immediate update to Epoch to reflect the chosen time system and format.

Remarks

GMAT supports five time systems or scales and two formats:

A.1USNO atomic time; GMAT’s internal time system
TAIInternational Atomic Time
TDBBarycentric Dynamical Time
TTTerrestrial Time
UTCCoordinated Universal Time
Gregorian

Text with the following format: dd mmm yyyy HH:MM:SS.FFF

dd

two-digit day of month

mmm

first three letters of month

yyyy

four-digit year

HH

two-digit hour

MM

two-digit minute

SS

two-digit second

FFF

three-digit fraction of second

Modified JulianFloating-point number of days from a reference epoch. In GMAT, the reference epoch is 05 Jan 1941 12:00:00.000 (JD 2430000.0).

The epoch can be set in multiple ways. The default method is to set the DateFormat field to the desired time system and format, then set the Epoch field to the desired epoch. This method cannot be used to get the epoch value, such as on the right-hand side of an assignment statement.

aSat.DateFormat = UTCGregorian
aSat.Epoch = '18 May 2012 12:00:00.000'

An alternate method is to specify the DateFormat in the parameter name. This method works in both “get” and “set” modes.

aSat.Epoch.UTCGregorian = '18 May 2012 12:00:00.000'
Report aReport aSat.Epoch.UTCGregorian

A third method can be used in “get” mode everywhere, but in “set” mode only in the mission sequence (i.e. after the BeginMissionSequence command).

aSat.UTCGregorian = '18 May 2012 12:00:00.000'
Report aReport aSat.UTCGregorian

GMAT uses the A.1 time system in the Modified Julian format for its internal calculations. The system converts all other systems and formats on input and again at output.

Leap Seconds

When converting to and from the UTC time system, GMAT includes leap seconds as appropriate, according to the tai-utc.dat data file from the IERS. This file contains the conversion between TAI and UTC, including all leap seconds that have been added or announced.

GMAT applies the leap second as the last second before the date listed in the tai-utc.dat file, which historically has been either January 1 or July 1. In the Gregorian date format, the leap second appears as a “60th second”: for example, “31 Dec 2008 23:59:60.000”. GMAT will correctly output this epoch, and will accept it as input. GMAT’s Modified Julian format is based on an 86,400-second day, however, and will repeat the first second of the following day. Input of the leap second in Modified Julian format is not supported. (See Release Notes for a known bug related to this functionality).

For epochs prior to the first entry in the leap-second file, the UTC and TAI time systems are considered identical (i.e. zero leap seconds are added). For epochs after the last entry, the leap second count from the last entry is used.

The tai-utc.dat file is periodically updated by the IERS when new leap seconds are announced. The latest version of this file can always be found at http://maia.usno.navy.mil/ser7/tai-utc.dat. To replace it, download the latest version and replace GMAT’s file in the location <GMAT>/data/time/tai-utc.dat, where <GMAT> is the install directory of GMAT on your system.

Examples

Setting the epoch for propagation

Create Spacecraft aSat
aSat.DateFormat = TAIModJulian
aSat.Epoch = 25562.5

Create ForceModel aFM
Create Propagator aProp
aProp.FM = aFM

BeginMissionSequence
Propagate aProp(aSat) {aSat.ElapsedDays = 1}

Plotting and reporting the epoch (syntax #1)

Create Spacecraft aSat
aSat.DateFormat = A1Gregorian
aSat.Epoch = '12 Jul 2015 08:21:45.921'

Create XYPlot aPlot
aPlot.XVariable = aSat.UTCModJulian
aPlot.YVariables = aSat.Earth.Altitude

Create Report aReport
aReport.Add = {aSat.UTCGregorian, aSat.EarthMJ2000Eq.ECC}

Plotting and reporting the epoch (syntax #2)

Create Spacecraft aSat
aSat.DateFormat = TTGregorian
aSat.Epoch = '01 Dec 1978 00:00:00.000'

Create XYPlot aPlot
aPlot.XVariable = aSat.Epoch.TTModJulian
aPlot.YVariables = aSat.Earth.RMAG

Create Report aReport
aReport.Add = {aSat.Epoch.A1Gregorian, aSat.Earth.RMAG}

Spacecraft Hardware

Spacecraft Hardware — Add hardware to a spacecraft

Description

The hardware fields allow you to attach pre-configured hardware models to a spacecraft. Current models include FuelTank and Thruster. Before you attach a hardware model to a Spacecraft, you must first create the model.

See Also: FuelTank, Thruster

Fields

FieldDescription
Tanks

This field is used to attach FuelTank(s) to a Spacecraft. In a script command, an empty list, e.g., DefaultSC.Tanks={}, is allowed and is used to indicate that no FuelTank(s) is attached to the spacecraft.

Data Type

Reference Array

Allowed Values

Any user-defined FuelTank.

Access

set

Default Value

N/A

Units

N/A

Interfaces

GUI, script.

Thrusters

This field is used to attach Thruster(s) to a Spacecraft. In a script command, an empty list, e.g., DefaultSC.Thrusters={}, is allowed and is used to indicate that no Thrusters are attached to the spacecraft.

Data Type

Reference Array

Allowed Values

Any user-defined Thruster.

Access

set

Default Value

N/A

Units

N/A

Interfaces

GUI, script

GUI

There are two spacecraft hardware items, the FuelTank and the Thruster, that can be attached to a Spacecraft. Here, we describe the method used to create and then attach these items to a Spacecraft. For details on how to configure the FuelTank and Thruster resources, see the help for the individual hardware item.

As shown below, to add a FuelTank to your script, highlight the Hardware resource and then right click to add a FuelTank.

To add a Thruster to your script, highlight the Hardware resource and then right click to add a Thruster.

Thus far, we have created both a FuelTank and a Thruster. Next, we attach both the FuelTank and the Thruster to a particular Spacecraft. To do this, double click on the desired Spacecraft under the Spacecraft resource to bring up the associated GUI panel. Then click on the Tanks tab to bring up the following GUI display.

Next, select the desired FuelTank and use the right arrow button to attach the FuelTank to the Spacecraft as shown below. Then click the Apply button.

Similarly, to attach a Thruster to a Spacecraft, double click on the desired Spacecraft under the Spacecraft resource and then select the Actuators tab. Then select the desired Thruster and use the right arrow to attach the Thruster to the Spacecraft as shown below. Finally, click the Apply button.

Remarks

To actually use the Thruster to apply a finite burn to a Spacecraft, additional steps are required. For example, when you create the Thruster resource, you have to associate a FuelTank with the Thruster. For details on this and related matters, see the help for the FuelTank, Thruster, and FiniteBurn resources.

Examples

Create a default Spacecraft. Create FuelTank and Thruster resources and attach them to the Spacecraft.

% Create default Spacecraft FuelTank, and Thruster Resources
Create Spacecraft DefaultSC
Create FuelTank FuelTank1
Create Thruster Thruster1

%  Attach FuelTank and Thruster to the spacecraft
DefaultSC.Thrusters = {Thruster1}
DefaultSC.Tanks = {FuelTank1}

BeginMissionSequence      

Spacecraft Orbit State

Spacecraft Orbit State — The orbital initial conditions

Description

GMAT supports a suite of state types for defining the orbital state, including Cartesian and Keplerian, among others. In addtion, you can define the orbital state in different coordinate systems, for example EarthMJ2000Eq and EarthFixed. GMAT provides three general state types that can be used with any coordinate system: Cartesian, SphericalAZFPA, and SphericalRADEC. There are three additional state types that can be used with coordinate systems centered at a celestial body: Keplerian, ModifiedKeplerian, and Equinoctial.

In the section called “Remarks” below, we describe each state type in detail including state-type definitions, singularities, and how the state fields interact with the CoordinateSystem and Epoch fields. There are some limitations when setting the orbital state during initialization, which are discussed in the section called “Remarks”. We also include examples for setting each state type in commonly used coordinate systems.

See Also: Spacecraft, Propagator, and Spacecraft Epoch

Fields

FieldDescription
AOP

The orbital argument of periapsis expressed in the coordinate system chosen in the CoordinateSystem field.

Data Type

Real

Allowed Values

-∞ < Real < ∞

Access

set, get

Default Value

314.1905515359921

Units

deg.

Interfaces

GUI, script

AZI

The orbital velocity azimuth expressed in the coordinate system chosen in the CoordinateSystem field.

Data Type

Real

Allowed Values

-∞ < Real < ∞

Access

set, get

Default Value

82.37742168155043

Units

deg.

Interfaces

GUI, script

DEC

The declination of the orbital position expressed in the coordinate system chosen in the CoordinateSystem field.

Data Type

Real

Allowed Values

-90 <= Real <= 90

Access

set, get

Default Value

10.37584492005105

Units

deg.

Interfaces

GUI, script

DECV

The declination of orbital velocity expressed in the coordinate system chosen in the CoordinateSystem field.

Data Type

Real

Allowed Values

-90 <= Real <= 90

Access

set, get

Default Value

7.747772036108118

Units

deg.

Interfaces

GUI, script

ECC

The orbital eccentricity expressed in the coordinate system chosen in the CoordinateSystem field.

Data Type

Real

Allowed Values

ECC < 0.9999999 or ECC > 1.0000001. If ECC > 1, SMA must be < 0

Access

set, get

Default Value

0.02454974900598137

Units

N/A

Interfaces

GUI, script

EquinoctialH

A measure of the orbital eccentricity and argument of periapsis. EquinoctialH and EquinoctialK together govern how elliptic an orbit is and where the periapsis is located. EquinotialH = ECC * sin(AOP) .

Data Type

Real

Allowed Values

-0.99999 < EquinoctialH < 0.99999, AND sqrt(EquinoctialH^2 + EquinoctialK^2) < 0.99999

Access

set, get

Default Value

-0.02423431419337062

Units

dimless

Interfaces

GUI, script

EquinoctialK

A measure of the orbital eccentricity and argument of periapsis. EquinoctialH and EquinoctialK together govern how elliptic an orbit is and where the periapsis is located. EquinotialK = ECC * cos(AOP)

Data Type

Real

Allowed Values

-0.99999 < EquinoctialK < 0.99999, AND sqrt(EquinoctialH^2 + EquinoctialK^2) < 0.99999

Access

set, get

Default Value

-0.003922778585859663

Units

dimless

Interfaces

GUI, script

EquinoctialP

A measure of the orientation of the orbit. EquinoctialP and EquinoctialQ together govern how an orbit is oriented. EquinotialP = tan(INC/2)*sin(RAAN).

Data Type

Real

Allowed Values

-Inf <= Real <= Inf

Access

set, get

Default Value

-0.09038834725719359

Units

dimless

Interfaces

GUI, script

EquinoctialQ

A measure of the orientation of the orbit. EquinoctialP and EquinoctialQ together govern how an orbit is oriented. EquinotialQ = tan(INC/2)*cos(RAAN).

Data Type

Real

Allowed Values

-Inf <= Real <= Inf

Access

set, get

Default Value

0.06716454898232072

Units

dimless

Interfaces

GUI, script

FPA

The orbital flight path angle expressed in the coordinate system chosen in the CoordinateSystem field.

Data Type

Real

Allowed Values

0<= Real <= 180

Access

set, get

Default Value

88.60870365370448

Units

Deg.

Interfaces

GUI, script

INC

The orbital inclination expressed in the coordinate system chosen in the CoordinateSystem field.

Data Type

Real

Allowed Values

0<