User Guide
R2016a
www.nasa.gov
general mission analysis tool
GMAT
General Mission Analysis Tool (GMAT)
User Guide
The GMAT Development Team
General Mission Analysis Tool (GMAT): User Guide
Table of Contents
Documentation Overview .................................................................................................. ix
Using GMAT .................................................................................................................... 1
Welcome to GMAT ................................................................................................... 3
Features Overview ............................................................................................. 3
Heritage ............................................................................................................ 4
Licensing .......................................................................................................... 4
Platform Support .............................................................................................. 4
Contributors ...................................................................................................... 5
Getting Started .......................................................................................................... 7
Installation ........................................................................................................ 7
Running GMAT ................................................................................................ 7
Sample Missions ................................................................................................ 8
Getting Help ..................................................................................................... 8
Tour of GMAT ......................................................................................................... 9
User Interfaces Overview ................................................................................... 9
Resources Tree ................................................................................................ 14
Mission Tree ................................................................................................... 17
Command Summary ........................................................................................ 26
Output Tree .................................................................................................... 29
Script Editor ................................................................................................... 29
Configuring GMAT ................................................................................................. 35
File Structure ................................................................................................... 35
Configuring Data Files ..................................................................................... 38
Tutorials .......................................................................................................................... 41
Simulating an Orbit .................................................................................................. 43
Objective and Overview ................................................................................... 43
Configure the Spacecraft .................................................................................. 43
Configure the Propagator ................................................................................. 45
Configure the Propagate Command ................................................................... 46
Run and Analyze the Results ............................................................................ 48
Simple Orbit Transfer .............................................................................................. 51
Objective and Overview ................................................................................... 51
Configure Maneuvers, Differential Corrector, and Graphics ................................. 51
Configure the Mission Sequence ....................................................................... 52
Run the Mission .............................................................................................. 58
Target Finite Burn to Raise Apogee .......................................................................... 61
Objective and Overview ................................................................................... 61
Create and Configure Spacecraft Hardware and Finite Burn ................................. 61
Create the Differential Corrector and Target Control Variable .............................. 67
Configure the Mission Sequence ....................................................................... 67
Run the Mission .............................................................................................. 72
Mars B-Plane Targeting ............................................................................................ 75
Objective and Overview ................................................................................... 75
Configure Fuel Tank, Spacecraft properties, Maneuvers, Propagators, Differential
Corrector, Coordinate Systems and Graphics ...................................................... 77
Configure the Mission Sequence ....................................................................... 82
iii
General Mission Analysis Tool
(GMAT)
Run the Mission with first Target Sequence ........................................................ 93
Run the Mission with first and second Target Sequences .................................... 103
Optimal Lunar Flyby using Multiple Shooting ........................................................... 107
Objective and Overview ................................................................................. 107
Configure Coordinate Systems, Spacecraft, Optimizer, Propagators, Maneuvers,
Variables, and Graphics .................................................................................. 110
Configure the Mission Sequence ...................................................................... 115
Design the Trajectory ..................................................................................... 123
Mars B-Plane Targeting Using GMAT Functions ...................................................... 131
Objective and Overview ................................................................................. 131
Configure Fuel Tank, Spacecraft properties, Maneuvers, Propagators, Differential
Corrector, Coordinate Systems and Graphics .................................................... 133
Configure the Mission Sequence ...................................................................... 140
Run the Mission with first Target Sequence ...................................................... 144
Run the Mission with first and second Target Sequences .................................... 152
Finding Eclipses and Station Contacts ...................................................................... 155
Objective and Overview ................................................................................. 155
Load the Mission ........................................................................................... 155
Configure GMAT for Event Location .............................................................. 156
Configure and Run the Eclipse Locator ............................................................ 158
Configure and Run the Contact Locator ........................................................... 161
Further Exercises ........................................................................................... 165
Electric Propulsion ................................................................................................. 167
Objective and Overview ................................................................................. 167
Create and Configure Spacecraft Hardware and Finite Burn ............................... 167
Configure the Mission Sequence ...................................................................... 173
Run the Mission ............................................................................................ 174
Simulate DSN Range and Doppler Data .................................................................. 175
Objective and Overview ................................................................................. 175
Create and configure the spacecraft, spacecraft transponder, and related parameters ............................................................................................................... 176
Create and configure the Ground Station and related parameters ......................... 177
Define the types of measurements to be simulated ............................................ 179
Create and configure Force model and propagator ............................................ 180
Create and configure Simulator object .............................................................. 180
Run the mission and analyze the results ........................................................... 181
Create a more realistic GMAT Measurement Data (GMD) ................................. 183
References ..................................................................................................... 186
Appendix A – Determination of Measurement Noise Values .............................. 186
Orbit Estimation using DSN Range and Doppler Data .............................................. 189
Objective and Overview ................................................................................. 189
Create and configure the spacecraft, spacecraft transponder, and related parameters ............................................................................................................... 190
Create and configure the Ground Station and related parameters ......................... 191
Define the types of measurements that will be processed ................................... 194
Create and configure Force model and propagator ............................................ 195
Create and configure BatchEstimatorInv object ................................................ 196
Run the mission and analyze the results ........................................................... 197
References ..................................................................................................... 206
iv
General Mission Analysis Tool
(GMAT)
Appendix A – GMAT Message Window Output ............................................... 207
Appendix B – Zeroth Iteration Plots of Observation Residuals ........................... 209
Appendix C – First Iteration Plots of Observation Residuals .............................. 210
Reference Guide ............................................................................................................ 211
I. Resources ........................................................................................................... 213
Antenna ........................................................................................................ 215
Array ............................................................................................................. 217
Barycenter ..................................................................................................... 221
BatchEstimatorInv ......................................................................................... 227
CelestialBody ................................................................................................. 235
CoordinateSystem ........................................................................................... 253
ContactLocator .............................................................................................. 273
DifferentialCorrector ...................................................................................... 285
ElectricTank .................................................................................................. 291
ElectricThruster ............................................................................................. 295
EclipseLocator ............................................................................................... 307
EphemerisFile ................................................................................................ 317
ErrorModel ................................................................................................... 331
FileInterface ................................................................................................... 335
FiniteBurn ..................................................................................................... 339
FminconOptimizer ......................................................................................... 345
Formation ..................................................................................................... 351
ChemicalTank ................................................................................................ 355
GMATFunction ............................................................................................. 365
GroundStation ............................................................................................... 381
GroundTrackPlot ........................................................................................... 391
ImpulsiveBurn ............................................................................................... 399
LibrationPoint ................................................................................................ 407
MatlabFunction .............................................................................................. 413
NuclearPowerSystem ...................................................................................... 417
OrbitView ..................................................................................................... 421
Propagator ..................................................................................................... 445
Receiver ......................................................................................................... 481
ReportFile ..................................................................................................... 483
Simulator ....................................................................................................... 493
SNOPT ......................................................................................................... 497
SolarPowerSystem .......................................................................................... 503
SolarSystem ................................................................................................... 509
Spacecraft ...................................................................................................... 515
Spacecraft Attitude ......................................................................................... 517
Spacecraft Ballistic/Mass Properties ................................................................. 551
Spacecraft Epoch ........................................................................................... 561
Spacecraft Hardware ....................................................................................... 571
Spacecraft Navigation ..................................................................................... 575
Spacecraft Orbit State ..................................................................................... 579
Spacecraft Visualization Properties ................................................................... 609
StatisticsAcceptFilter ....................................................................................... 615
StatisticsRejectFilter ........................................................................................ 619
String ............................................................................................................ 623
v
General Mission Analysis Tool
(GMAT)
TrackingFileSet ...............................................................................................
Transmitter ....................................................................................................
Transponder ..................................................................................................
ChemicalThruster ...........................................................................................
Variable .........................................................................................................
VF13ad .........................................................................................................
XYPlot ..........................................................................................................
II. Commands .......................................................................................................
Achieve .........................................................................................................
Assignment (=) ..............................................................................................
BeginFiniteBurn .............................................................................................
BeginMissionSequence ....................................................................................
BeginScript ....................................................................................................
CallGmatFunction ..........................................................................................
CallMatlabFunction ........................................................................................
CallPythonFunction ........................................................................................
ClearPlot .......................................................................................................
EndFiniteBurn ...............................................................................................
FindEvents ....................................................................................................
For ................................................................................................................
GetEphemStates() ..........................................................................................
Global ...........................................................................................................
If ..................................................................................................................
Maneuver ......................................................................................................
MarkPoint .....................................................................................................
Minimize .......................................................................................................
NonlinearConstraint .......................................................................................
Optimize .......................................................................................................
PenUpPenDown ............................................................................................
Propagate ......................................................................................................
Report ...........................................................................................................
RunEstimator .................................................................................................
RunSimulator .................................................................................................
Set ................................................................................................................
Stop ..............................................................................................................
Target ...........................................................................................................
Toggle ...........................................................................................................
Vary ..............................................................................................................
While ............................................................................................................
Write .............................................................................................................
III. System ............................................................................................................
Calculation Parameters ....................................................................................
Color ............................................................................................................
Command-Line Usage ....................................................................................
#Include Macro .............................................................................................
Keyboard Shortcuts ........................................................................................
MATLAB Interface ........................................................................................
Python Interface ............................................................................................
Script Language .............................................................................................
vi
625
633
635
639
659
663
667
673
675
677
687
693
695
697
703
707
711
715
717
723
727
733
739
743
747
751
755
759
765
769
781
785
787
791
793
795
803
807
815
819
823
825
865
883
885
891
893
897
899
General Mission Analysis Tool
(GMAT)
Startup File ....................................................................................................
Release Notes ................................................................................................................
GMAT R2016a Release Notes .................................................................................
GMAT R2015a Release Notes .................................................................................
GMAT R2014a Release Notes .................................................................................
GMAT R2013b Release Notes ................................................................................
GMAT R2013a Release Notes .................................................................................
GMAT R2012a Release Notes .................................................................................
GMAT R2011a Release Notes .................................................................................
Index ............................................................................................................................
911
917
917
920
928
934
938
942
949
961
vii
viii
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.
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.
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 perform targeting by application to a Mars transfer
trajectory where you will target desired B-plane conditions at Mars.
The Target Finite Burn to Raise Apogee tutorial shows how to use finite maneuvers with an application
to orbit apogee raising.
The Finding Eclipses and Station Contacts tutorial shows how to use GMAT to locate elipses and station
contacts.
ix
Documentation Overview
The Electric Propulsion tutorial shows how to configure GMAT to model electric propulsion systems.
The Mars B-Plane Targeting Using GMAT Functions tutorial shows how to use GMAT functions to
extend your analysis.
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.
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.
x
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.
Using GMAT
Welcome to GMAT
The General Mission Analysis Tool (GMAT) is the world’s only enterprise, multi-mission, open
source software system for space mission design, optimization, and navigation. The system supports
missions 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 mission support, engineering studies, as a tool for education, and public
engagement.
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.
Release R2016a is the first version of GMAT to contain production navigation functionality. We've
also added the ability to read and export script snippets from external files, the ability to write STK .e
ephem files, and added many new built-in math functions. See the R2016a Release Notes for other
additions and bug fixes.
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 chemical and electric system
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, SPK, and Code-500 ephemeris generation
Eclipse and station contact location
Optimization and Targeting
• Boundary value targeters
• Nonlinear, constrained optimization
3
Using GMAT
Welcome to GMAT
• 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
Python interface
User-defined functions (sub-routines)
Built in parameters and calculations in multiple coordinate systems
Orbit Determination Infrastructure
•
•
•
•
•
•
•
Batch estimator
Extensive statistical results reporting
DSN data types
Beta SN and GN data types (turned off but can be turned on for experimentation)
Measurement data editing
Media corrections
Error modeling
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
Python interface for custom external simulations and calculations
File interface for the TCOPS Vector Hold File format, for loading of initial spacecraft data
Command line interface for batch analysis
Heritage
GMAT has enabled and enhanced missions in nearly every NASA flight regime including enabling
new mission types, extending the life of existing missions, and enabling new science observations.
GMAT has supported 8 NASA missions and 10+ NASA proposal efforts. The system has experienced broad application and adoption around the world. To date, GMAT has been used by over 30
organizations, with 15 universities and 12 commercial firms publishing results in the open literature.
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 13,000 test cases for the system core and over 4000 test cases for the GUI
interface.
4
Welcome to GMAT
Using GMAT
For release R2016a, we have addressed issues on Windows including the GUI, and the Mac and
Linux console (GUI is provided but is in alpha form on Mac and Linux).
Note that this is the last 32-bit version of GMAT on Windows. Future versions will be 64-bit on
all platforms.
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. External particpants contribute to design, implementation, testing and documentation. We use a collaborative development model that enables innovation and actively involves the public and private sector having seen contributions from 12 commercial firms. External participants for R2015a include:
•
•
•
•
•
•
•
Thinking Systems, Inc. (system architecture and all aspects of development)
Omitron, Inc (testing, requirements, specifications)
Emergent Space Technologies, Inc.
Korea Aerospace Research Institute
Chonbuk National University, South Korea
Korea Advanced Institute of Science and Technology
Yonsei University, South Korea
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).
5
6
Using GMAT
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:
Installer
Binary bundle
Source 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 R2015a item in the Start menu. If you installed
7
Using GMAT
Getting Started
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.
2.
3.
4.
5.
Open GMAT.
On the toolbar click Open.
Navigate to the samples folder located in the GMAT root directory.
Double-click a script file of your choice.
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:
•
•
•
•
•
•
8
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: <gmat@gsfc.nasa.gov>
Using GMAT
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 1. GMAT Desktop (Windows)
9
Using GMAT
Menu Bar
Toolbar
Resources Tab
Resources Tree
Mission Tab
Mission Tree
10
Tour of GMAT
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.
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.
The Resources tab brings the Resources tree to the foreground of the
desktop.
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.
The Mission tab brings the Mission Tree to the foreground of the desktop.
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 rightclicking 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.
Tour of GMAT
Using GMAT
Figure 2. Undocked Mission Tree
Output Tab
Output Tree
Message Window
Status Bar
The Output tab brings the Output Tree to the foreground of the desktop.
The Output tree contains GMAT output such as report files and graphical
displays.
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.
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 below, the script editor is shown maximized in the GMAT
desktop and the items relevant to script editing are labeled.
11
Using GMAT
Tour of GMAT
Figure 3. GMAT Script Editor
Scripts Folder
Script Status Box
Save,Sync Button
Save,Sync,Run Button
Save As Button
Close
12
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.
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.
The Save,Sync button saves any script file changes to disk, makes
the script active, and synchronizes the GUI with the script.
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.
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.
The Close button closes the script editor.
Tour of GMAT
Using GMAT
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
13
Using GMAT
Tour of GMAT
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 4).
14
Tour of GMAT
Using GMAT
Figure 4. 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 5). Other folders have multiple objects that can be added and the user must first select the “Add” menu before
selecting the object; for example to add a ChemicalTank, right click the “Hardware” folder, select
“Add”, then the list of available resource types is displayed and the user can click “Fuel Tank” (Figure 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.
15
Using GMAT
Tour of GMAT
Figure 5. Folder menu for Spacecraft
Figure 6. 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 7).
Figure 7. 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:
16
Tour of GMAT
•
•
•
•
•
Using GMAT
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
17
Using GMAT
Tour of GMAT
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
18
Tour of GMAT
Using GMAT
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
19
Using GMAT
Tour of GMAT
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.
20
Tour of GMAT
Using GMAT
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
21
Using GMAT
Tour of GMAT
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,
22
Tour of GMAT
Using GMAT
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.
23
Using GMAT
Tour of GMAT
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
24
Tour of GMAT
Using GMAT
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
25
Using GMAT
Tour of GMAT
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.
Snapshot of a sample Command Summary is shown in the following figure.
26
Tour of GMAT
Using GMAT
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 Im27
Using GMAT
Tour of GMAT
pulsiveBurn resource. See the Coordinate Systems subsection below for more information on the
command summary contents when some data is undefined.
In the event when the orbit is nearly singular conic section and/or any of the keplerian elements are
undefined, an abbreviated Command Summary is displayed as shown in the Coordinate Systems
subsection below.
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. When the Coordinate System has a celestial body
at the origin, the Command Summary shows all supported data including Cartesian, Spherical,
Keplerian, Other OrbitData, and Planetodetic properties as shown in the GUI screenshot above.
When the Coordinate System does not have a celestial body at the origin, the CommandSummary
contains an abbreviated command summary as shown below.
Note: GMAT currently requires that the selected CoordinateSystem cannot reference a spacecraft.
Propagate Command: Propagate1
Spacecraft
: DefaultSC
Coordinate System: EarthMJ2000Eq
Time System
Gregorian
Modified Julian
-------------------------------------------------------------------UTC Epoch:
01 Jan 2000 15:19:28.000
21545.1385185185
TAI Epoch:
01 Jan 2000 15:20:00.000
21545.1388888889
TT Epoch:
01 Jan 2000 15:20:32.184
21545.1392613889
TDB Epoch:
01 Jan 2000 15:20:32.184
21545.1392613881
Cartesian State
--------------------------X =
7047.3574396928 km
Y = -821.00373455465 km
Z =
1196.0053110175 km
VX =
0.8470865225276 km/sec
VY =
7.3062391027010 km/sec
VZ =
1.1303623817297 km/sec
Spacecraft Properties
-----------------------------Cd
=
2.200000
Drag area
=
15.00000 m^2
Spherical State
-----------------------------RMAG =
7195.1179781105 km
RA
= -6.6448962577676 deg
DEC =
9.5683789596091 deg
VMAG =
7.4415324037805 km/s
AZI =
81.377585410118 deg
VFPA =
88.583915406742 deg
RAV =
83.386645244484 deg
DECV =
8.7370006427902 deg
28
Tour of GMAT
Using GMAT
Cr
=
Reflective (SRP) area =
Dry mass
=
Total mass
=
1.800000
1.000000 m^2
850.00000000000 kg
850.00000000000 kg
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.
29
Using GMAT
Tour of GMAT
The following figure shows a basic script editor session with the major features labeled.
Figure 8. 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 9. Active script indicators
30
Tour of GMAT
Using GMAT
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 8, 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 Mod- The mission has been modified in the script representation, but has not been synified
chronized 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 Modi- The mission has been modified in the GUI, but has not been synchronized to the
fied
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.
Unsynchro- The mission has been modified both in the GUI and in the script. The changes cannized
not 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
31
Using GMAT
2.
3.
4.
5.
Tour of GMAT
Closes all open windows (except the script editor itself)
Validates the script file
Refreshes the GUI by loading the saved script
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
32
Tour of GMAT
Using GMAT
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.
See the Keyboard Shortcuts reference page for the list of keyboard shortcuts that are available when
working in the script editor:
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.
33
Using GMAT
Tour of GMAT
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.
34
Using GMAT
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 10. 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 10. 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 11 and described below.
35
Using GMAT
Configuring GMAT
Figure 11. 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.
36
Configuring GMAT
Using GMAT
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 sample missions and scripts, ranging from a Hohmann transfer
to libration point station-keeping to Mars B-plane targeting. Example files begin with "Ex_" and
files that correspond 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, Python, and GMAT functions that are included in the GMAT distribution. You can also store your own custom functions in the subdirectories
named GMAT, Python, and MATLAB. GMAT includes those subdirectories in its search path to
locate functions referenced in GMAT scripts and GMAT functions.
37
Using GMAT
Configuring GMAT
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 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 by the IERS. To update your local file with the latest data, replace the file eopc04_08.62now in the data/planetary_coeff directory. Historical EOP data is available from the IERS
here and recent and predicted EOP data is avialable from the IERS here.
For use with GMAT's event location subsystem, you will also need to update the SPICE EOP
files, distributed by NAIF: http://naif.jpl.nasa.gov/pub/naif/generic_kernels/
pck. The high-fidelity earth_000101_yymmdd_yymmdd.bpc file is updated twice per week. For
more information on data configuration for event location, see the ContactLocator and EclipseLocator reference pages.
There are two leap second files provided with GMAT in the data/time directory. The
naif0011.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 taiutc.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.
38
Configuring GMAT
Using GMAT
Configuring the Python Inteface
GMAT contains an interface to Python. See the Python 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.
39
40
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.
Tutorials
Simulating an Orbit
Audience
Length
Prerequisites
Script File
Beginner
30 minutes
None
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.
2.
3.
4.
5.
Configure a Spacecraft and define its epoch and orbital elements.
Configure a Propagator.
Modify the default OrbitView plot to visualize the spacecraft trajectory.
Modify the Propagate command to propagate the spacecraft to periapsis.
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.
43
Tutorials
Simulating an Orbit
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 1. Sat Orbit State Settings
Field
Value
ECC
0.89652
INC
12.4606
RAAN
292.8362
AOP
218.9805
TA
180
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 12. Spacecraft State Setup
44
Simulating an Orbit
Tutorials
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.
In the Resources tree, double-click LowEarthProp.
Under Gravity, in the Degree box, type 10.
In the Order box, type 10.
In Atmosphere Model list, click JacchiaRoberts.
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 13.
10.Click OK.
1.
2.
3.
4.
5.
Figure 13. Force Model Configuration
45
Tutorials
Simulating an Orbit
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 14.
4. Click OK.
Figure 14. 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.
46
Simulating an Orbit
Tutorials
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 15.
Figure 15. Propagate Command ParameterSelectDialog Configuration
6. Click OK. Your screen should now match Figure 16.
7. Click OK.
47
Tutorials
Simulating an Orbit
Figure 16. 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 17 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:
Click the Mission tab to display the Mission tree.
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.
1.
2.
48
Simulating an Orbit
Tutorials
Figure 17. Orbit View Plot after Mission Run
49
50
Tutorials
Simple Orbit Transfer
Audience
Length
Prerequisites
Script File
Beginner
30 minutes
Complete Simulating an Orbit
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.
2.
3.
4.
5.
Create and configure a DifferentialCorrector resource.
Modify the DefaultOrbitView to visualize the trajectory.
Create two ImpulsiveBurn resources with default settings.
Create a Target sequence to (1) raise apoapsis to geosynchronous altitude and (2) circularize
the orbit.
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
51
Tutorials
Simple Orbit Transfer
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.
2.
In the Resource tree, expand the Solvers folder if it isn’t already.
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.
2.
In the Resource Tree, double-click DefaultOrbitView to edit its properties.
Set the values shown in the table below.
Table 2. DefaultOrbitView settings
3.
Field
Value
Solver Iterations, under Drawing Option
Current
Axis, under View Up Defintion
X
View Point Vector boxes, under View Definition
0, 0, and 120000 respectively
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.
2.
3.
4.
In the Resources tree, right-click DefaultIB and click Rename.
In the Rename box, type TOI, an acronym for Transfer Orbit Insertion, and click OK.
Right-click the Burns folder, point to Add, and click ImpulsiveBurn.
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 Simulating an Orbit tutorial.
Configure the Initial Propagate Command
1.
52
Click on the Mission tab to show the Mission tree.
Simple Orbit Transfer
2.
3.
Tutorials
Configure Propagate1 to propagate to DefaultSC.Earth.Periapsis.
Rename Propagate1 to Prop To Periapsis.
Create the Target Sequence
Now create the commands necessary to perform the Target sequence. Figure 18 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 18. Final Mission Sequence for the Hohmann Transfer
To create the Target sequence:
1.
2.
3.
4.
5.
6.
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.
Right-click Target1 and click Rename.
Type Hohmann Transfer and click OK.
Right-click Hohmann Transfer, point to Append, and click Vary.
Rename Vary1 to Vary TOI.
Complete the Target sequence by appending the commands in Table 3.
Table 3. Additional Target Sequence Commands
Command
Name
Maneuver
Perform TOI
Propagate
Prop To Apoapsis
Achieve
Achieve RMAG = 42165
Vary
Vary GOI
Maneuver
Perform GOI
Achieve
Achieve ECC = 0.005
53
Tutorials
Simple Orbit Transfer
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.
2.
3.
4.
5.
In the Mission tree, right-click End Hohmann Transfer, point to Insert After, and click
Propagate. A new Propagate3 command will appear.
Rename Propagate3 to Prop One Day.
Double-click Prop One Day to edit its properties.
Under Condition, replace the value 12000.0 with 86400, the number of seconds in one day.
Click OK to save these changes.
Figure 19. Prop One Day Command Configuration
54
Simple Orbit Transfer
Tutorials
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.
2.
3.
4.
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.
In the Initial Value box, type 1.0.
In the Max Step box, type 0.5.
Click OK to save these changes.
Figure 20. Vary TOI Command Configuration
Configure the Perform TOI Command
1.
2.
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.
Click OK.
Figure 21. Perform TOI Command Configuration
Configure the Prop to Apoapsis Command
1.
Double-click Prop to Apoapsis to edit its properties.
55
Tutorials
Simple Orbit Transfer
2.
3.
Under
Parameter,
replace
DefaultSC.Earth.Apoapsis.
Click OK to save these changes.
DefaultSC.ElapsedSecs
with
Figure 22. Prop to Apoapsis Command Configuration
Configure the Achieve RMAG = 42165 Command
1.
2.
3.
4.
Double-click Achieve RMAG = 42165 to edit its properties.
Notice that Goal is set to DefaultSC.Earth.RMAG. This is what we need, so we make no
changes here.
In the Value box, type 42164.169, a more precise number for the radius of a geosynchronous
orbit (in kilometers).
Click OK to save these changes.
Figure 23. Achieve RMAG = 42165 Command Configuration
Configure the Vary GOI Command
1.
2.
56
Double-click Vary GOI to edit its properties.
Next to Variable, click the Edit button.
Simple Orbit Transfer
3.
4.
Tutorials
Under Object List, click GOI.
In the Object Properties list, double-click Element1 to move it to the Selected Value(s) list.
See the image below for results.
Figure 24. Vary GOI Parameter Selection
5.
6.
7.
8.
Click OK to close the ParameterSelectDialog window.
In the Initial Value box, type 1.0.
In the MaxStep text box, type 0.2.
Click OK to save these changes.
Figure 25. Vary GOI Command Configuration
Configure the Perform GOI Command
1.
Double-click Perform GOI to edit its properties.
57
Tutorials
Simple Orbit Transfer
2.
3.
In the Burn list, click GOI.
Click OK to save these changes.
Figure 26. Perform GOI Command Configuration
Configure the Achieve ECC = 0.005 Command
1.
2.
3.
4.
5.
6.
7.
Double-click Achieve ECC = 0.005 to edit its properties.
Next to Goal, click the Edit button.
In the Object Properties list, double-click ECC.
Click OK to close the ParameterSelectDialog window.
In the Value box, type 0.005.
In the Tolerance box, type 0.0001.
Click OK to save these changes.
Figure 27. 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.
58
Simple Orbit Transfer
Tutorials
Figure 28. 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.
2.
3.
In the Mission tree, double-click Hohmann Transfer to edit its properties.
Click Apply Corrections.
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.
59
60
Tutorials
Target Finite Burn to Raise Apogee
Audience
Length
Prerequisites
Script File
Intermediate level
45 minutes
Complete Simulating an Orbit and Simple Orbit Transfer
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.
2.
3.
Create and configure the Spacecraft hardware and FiniteBurn resources
Create the DifferentialCorrector and Target Control Variable
Configure the Mission Sequence. To do this, we will
4.
a. Create Begin/End FiniteBurn commands with default settings.
b. Create a Target sequence to achieve a 12000 km apogee radius.
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 ChemicalThruster and
a ChemicalTank and then attach the newly created ChemicalTank to the ChemicalThruster.
61
Tutorials
Target Finite Burn to Raise Apogee
1.
2.
3.
4.
5.
In the Resources tree, right-click on the Hardware folder, point to Add, and click ChemicalThruster. A resource named ChemicalThruster1 will be created.
In the Resources tree, right-click on the Hardware folder, point to Add, and click ChemicalTank. A resource named ChemicalTank1 will be created.
Double-click ChemicalThruster1 to edit its properties.
Select the Decrement Mass box so that GMAT will model fuel use associated with a finite
burn.
Use the drop down menu to the right of the Tank field to select ChemicalTank1 as the fuel
source for ChemicalThruster1. Click OK.
Figure 29 below shows the default ChemicalTank1 configuration that we will use and Figure 30
shows the finished ChemicalThruster1 configuration.
Figure 29. ChemicalTank1 Configuration
62
Target Finite Burn to Raise Apogee
Tutorials
Figure 30. ChemicalThruster1 Configuration
Note that the default Thruster1 Coordinate System, as shown in Figure 30, 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 ChemicalThruster1
polynomial coefficients as follows.
Modify Thruster1 Thrust Coefficients
1.
2.
In the Resources tree, double-click ChemicalThruster1 to edit its properties
Click the Edit Thruster Coef. button to bring up the ThrusterCoefficientDialog box, shown
in Figure 31. Replace the default C1 coefficient value of 10 with 1000. Click OK.
63
Tutorials
Target Finite Burn to Raise Apogee
Figure 31. ChemicalThruster1 Thrust Coefficients
The exact form of the pre-defined Thrust polynomial, associated with the coefficients above, are
given in the ChemicalThruster 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 ChemicalTank1 and Thruster1 to DefaultSC
1.
2.
3.
64
In the Resources tree, double-click DefaultSC to edit its properties.
Select the Tanks tab. In the Available Tanks column, select ChemicalTank1. Then click the
right arrow button to add ChemicalTank1 to the SelectedTanks list. Click Apply.
Select the Actuators tab. In the Available Thrusters column, select ChemicalThruster1.
Then click the right arrow button to add ChemicalThruster1 to the SelectedThrusters list.
Click OK.
Target Finite Burn to Raise Apogee
Tutorials
Figure 32. Attach ChemicalTank1 to DefaultSC
65
Tutorials
Target Finite Burn to Raise Apogee
Figure 33. Attach ChemicalThruster1 to DefaultSC
Create the Finite Burn Maneuver
We’ll need a single FiniteBurn resource for this tutorial.
1.
2.
3.
In the Resources tree, right-click the Burns folder and add a FiniteBurn. A resource named
FiniteBurn1 will be created.
Double-click FiniteBurn1 to edit its properties.
Use the menu to the right of the Thruster field to select ChemicalThruster1 as the thruster
associated with FiniteBurn1. Click OK.
Figure 34. Creation of FiniteBurn Resource FiniteBurn1
66
Target Finite Burn to Raise Apogee
Tutorials
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.
2.
In the Resources tree, expand the Solvers folder if it isn’t already.
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.
2.
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
=> button to create the variable, then click Close.
To verify that we have created this new variable correctly, double-click BurnDuration to view
its properties.
Figure 35. 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.
2.
3.
Click on the Mission tab to show the Mission tree.
Configure Propagate1 to propagate to DefaultSC.Earth.Periapsis.
Rename Propagate1 to Prop To Perigee.
67
Tutorials
Target Finite Burn to Raise Apogee
Figure 36. Prop To Perigee Command Configuration
Create the Target Sequence
Now create the commands necessary to perform the Target sequence. Figure 37 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 37. Final Mission Sequence
To create the Target sequence:
1.
2.
3.
4.
68
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.
Right-click Target1 and click Rename. Type Raise Apogee and click OK.
Right-click Raise Apogee, point to Append, and click Vary. Rename the newly created command as Vary Burn Duration.
Right-click Vary Burn Duration, point to Insert After, and click BeginFiniteBurn. Rename
the newly created command as Turn Thruster On.
Target Finite Burn to Raise Apogee
5.
Tutorials
Complete the Target sequence by inserting the commands shown in Table 4.
Table 4. Additional Target Sequence Commands
Command
Name
Propagate
Prop BurnDuration
EndFiniteBurn
Turn Thruster Off
Propagate
Prop To Apogee
Achieve
Achieve 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.
2.
3.
Double-click Raise Apogee to edit its properties.
In the ExitMode list, click SaveAndContinue. This instructs GMAT to save the final solution
of the targeting problem after you run it.
Click OK to save these changes.
Figure 38. Raise Apogee Command Configuration
Configure the Vary Burn Duration Command
1.
2.
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.
In the Initial Value box, type 200
69
Tutorials
Target Finite Burn to Raise Apogee
3.
4.
5.
In the Upper box, type 10000
In the Max Step box, type 100.
Click OK to save these changes.
Figure 39. Vary Burn Duration Command Configuration
Configure the Turn Thruster On Command
1.
2.
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.
Click OK.
Figure 40. Turn Thruster On Command Configuration
Configure the Prop BurnDuration Command
1.
2.
3.
70
Double-click Prop BurnDuration to edit its properties.
We will use the default Parameter value of DefaultSC.ElapsedSecs.
Under Condition, replace the default value with Variable, BurnDuration.
Target Finite Burn to Raise Apogee
4.
Tutorials
Click OK to save these changes.
Figure 41. Prop BurnDuration Command Configuration
Configure the Turn Thruster Off Command
1.
2.
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..
Click OK.
Figure 42. Turn Thruster Off Command Configuration
Configure the Prop To Apogee Command
1.
2.
3.
Double-click Prop to Apogee to edit its properties.
Under Parameter, replace DefaultSC.ElapsedSecs with DefaultSC.Earth.Apoapsis.
Click OK to save these changes.
71
Tutorials
Target Finite Burn to Raise Apogee
Figure 43. Prop To Apogee Command Configuration
Configure the Achieve Apogee Radius = 12000 Command
1.
2.
3.
4.
Double-click Achieve Apogee Radius = 12000 to edit its properties.
Notice that Goal is set to DefaultSC.Earth.RMAG. This is what we need, so we make no
changes here.
In the Value box, type 12000
Click OK to save these changes
Figure 44. 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
72
Target Finite Burn to Raise Apogee
Tutorials
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 "faceon." Visually verify that apogee has indeed been raised.
Figure 45. 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.
73
Tutorials
Target Finite Burn to Raise Apogee
1.
2.
3.
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.
View the Turn Thruster On command summary. Note that, as expected, prior to the start of
the maneuver, the fuel mass is 756 kg.
View the Turn Thruster Off command summary.
a.
4.
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.
b. 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.
View the Prop To Apogee command summary.
a.
b.
74
We note that the mean anomaly is 180 degrees which proves that we are indeed at apogee.
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.
Tutorials
Mars B-Plane Targeting
Audience
Length
Prerequisites
Advanced
75 minutes
Complete Simulating an Orbit, Simple Orbit Transfer and a basic understanding
of B-Planes and their usage in targeting is required.
Tut_Mars_B_Plane_Targeting.script
Script File
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 46 and Figure 47 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 BPlane. Once the spacecraft gets close to Mars, then an orbit insertion maneuver can be
performed to capture into Mars orbit.
Figure 46. Geometry of the B-Plane as seen
from a viewpoint perpendicular to the B-Plane
75
Tutorials
Mars B-Plane Targeting
Figure 47. 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 Binormal (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.
2.
3.
4.
5.
6.
7.
76
Modify the DefaultSC to define spacecraft’s initial state. The initial state is an out-going hyperbolic trajectory that is with respect to Earth.
Create and configure a Fuel Tank resource.
Create two ImpulsiveBurn resources with default settings.
Create and configure three Propagators: NearEarth, DeepSpace and NearMars
Create and configure DifferentialCorrector resource.
Create and configure three DefaultOrbitView resources to visualize Earth, Sun and Mars
centered trajectories.
Create and configure three CoordinateSystems: Earth, Sun and Mars centered.
Mars B-Plane Targeting
Tutorials
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.
2.
3.
4.
5.
In the Resources tree, right-click the Hardware folder, point to Add and click ChemicalTank. A new resource called ChemicalTank1 will be created.
Right-clickChemicalTank1 and click Rename.
In theRename box, type MainTank and click OK.
Double click onMainTank to edit its properties.
Set the values shown in the table below.
Table 5. MainTank settings
6.
Field
Value
Fuel Mass
1718
Fuel Density
1000
Pressure
5000
Volume
2
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.
2.
3.
4.
In the Resources tree, under Spacecraft folder, right-click DefaultSC and click Rename.
In the Rename box, type MAVEN and click OK.
Double-click on MAVEN to edit its properties. Make sure Orbit tab is selected.
Set the values shown in the table below.
77
Tutorials
Mars B-Plane Targeting
Table 6. MAVEN settings
5.
6.
7.
8.
Field
Value
Epoch Format
UTCGregorian
Epoch
18 Nov 2013 20:26:24.315
Coordinate System
EarthMJ2000Eq
State Type
Keplerian
SMA under Elements
-32593.21599272796
ECC under Elements
1.202872548116185
INC under Elements
28.80241266404142
RAAN under Elements
173.9693759331483
AOP under Elements
240.9696529532764
TA under Elements
359.9465533778069
Click on Tanks tab now.
Under Available Tanks, you'll see MainTank. This is the fuel tank that we created earlier.
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.
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.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
78
In the Resources tree, under the Burns folder, right-click DefaultIB and click Rename.
In the Rename box, type TCM, an acronym for Trajectory Correction Maneuver and click
OK to edit its properties.
Double-Click TCM to edit its properties to edit its properties.
Check Decrement Mass under Mass Change.
For Tank field under Mass Change, select MainTank from drop down menu.
Click OK to save these changes.
Right-click theBurns folder, point to Add, and click ImpulsiveBurn. A new resource called
ImpulsiveBurn1 will be created.
Rename the new ImpulsiveBurn1 resource to MOI, an acronym for Mars Orbit Insertion
and click OK.
Double-click MOI to edit its properties.
For Origin field under Coordinate System, select Mars.
Check Decrement Mass under Mass Change.
For Tank field under Mass Change, select MainTank from the drop down menu.
Click OK to save these changes.
Mars B-Plane Targeting
Tutorials
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.
2.
3.
4.
In the Resources tree, under the Propagators folder, right-click DefaultProp and click Rename.
In the Rename box, type NearEarth and click OK.
Double-click on NearEarth to edit its properties.
Set the values shown in the table below.
Table 7. NearEarth settings
5.
6.
7.
8.
9.
Field
Value
Initial Step Size under Integrator
600
Accuracy under Integrator
1e-013
Min Step Size under Integrator
0
Max Step Size under Integrator
600
Model under Gravity
JGM-2
Degree under Gravity
8
Order under Gravity
8
Atmosphere Model under Drag
None
Point Masses under Force Model
Add Luna and Sun
Use Solar Radiation Pressure under Force Model
Check this field
Click on OK to save these changes.
Right-click the Propagators folder and click Add Propagator. A new resource called Propagator1 will be created.
Rename the new Propagator1 resource to DeepSpace and click OK.
Double-click DeepSpace to edit its properties.
Set the values shown in the table below.
79
Tutorials
Mars B-Plane Targeting
Table 8. DeepSpace settings
Field
Value
Type under Integrator
PrinceDormand78
Initial Step Size under Integrator
600
Accuracy under Integrator
1e-012
Min Step Size under Integrator
0
Max Step Size under Integrator
864000
Central Body under Force Model
Sun
Primary Body under Force Model
None
Point Masses under Force Model
Add Earth, Luna, Sun, Mars,
Jupiter, Neptune, Saturn,
Uranus, Venus
Use Solar Radiation Pressure under Force Model
Check 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 9. NearMars settings
Field
Value
Type under Integrator
PrinceDormand78
Initial Step Size under Integrator
600
Accuracy under Integrator
1e-012
Min Step Size under Integrator
0
Max Step Size under Integrator
86400
Central Body under Force Model
Mars
Primary Body under Force Model
Mars
Model under Gravity
Mars-50C
Degree under Gravity
8
Order under Gravity
8
Atmosphere Model under Drag
None
Point Masses under Force Model
Add Sun
Use Solar Radiation Pressure under Force Model
Check this field
15. Click OK to save the changes.
80
Mars B-Plane Targeting
Tutorials
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.
2.
3.
In the Resources tree, expand the Solvers folder if it isn’t already.
Right-click the Boundary Value Solvers folder, point to Add, and click DifferentialCorrector. A new resource called DC1 will be created.
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.
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.
1.
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.
2.
3.
4.
5.
In the Resources tree, under Output folder, right-click DefaultOrbitView and click Rename.
In the Rename box, type EarthView and click OK.
In the Output folder, delete DefaultGroundTrackPlot.
Double-click EarthView to edit its properties.
Set the values shown in the table below.
Table 10. EarthView settings
Field
Value
View Scale Factor under View Definition
4
View Point Vector boxes, under View Definition
0, 0, 30000
81
Tutorials
Mars B-Plane Targeting
Click OK to save these changes.
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.
6.
7.
Table 11. SolarSystemView settings
Field
Value
From Celestial Object under View Object, add following Mars, Sun (Do not remove
objects to Selected Celestial Object box
Earth)
Coordinate System under View Definition
SunEcliptic
View Point Reference under View Definition
Sun
View Point Vector boxes, under View Definition
0, 0, 5e8
View Direction under View Definition
Sun
Coordinate System under View Up Definition
SunEcliptic
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 12. MarsView settings
Field
Value
From Celestial Object under View Object, add following Mars (You don’t have to reobject to Selected Celestial Object box
move Earth)
Coordinate System under View Definition
MarsInertial
View Point Reference under View Definition
Mars
View Point Vector boxes, under View Definition
22000, 22000, 0
View Direction under View Definition
Mars
Coordinate System under View Up Definition
MarsInertial
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 Simulating an Orbit tutorial.
82
Mars B-Plane Targeting
Tutorials
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 48 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 48. Mission Sequence for the First Target sequence
To create the first Target sequence:
Click on the Mission tab to show the Mission tree.
You’ll see that there already exists a Propagate1 command. We need to delete this command
Right-click on Propagate1 command and click Delete.
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 13.
1.
2.
3.
4.
83
Tutorials
Mars B-Plane Targeting
Table 13. Additional First Target Sequence Commands
Command
Name
Propagate
Prop 12 Days to TCM
Vary
Vary TCM.V
Vary
Vary TCM.N
Vary
Vary TCM.B
Maneuver
Apply TCM
Propagate
Prop 280 Days
Propagate
Prop to Mars Periapsis
Achieve
Achieve BdotT
Achieve
Achieve 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.
2.
3.
84
1Double-click Target desired B-plane Coordinates to edit its properties.
In the ExitMode list, click SaveAndContinue. This instructs GMAT to save the final solution
of the targeting problem after you run it.
Click OK to save these changes.
Mars B-Plane Targeting
Tutorials
Figure 49. Target desired B-plane Coordinates Command Configuration
Configure the Prop 3 Days Command
1.
2.
3.
4.
5.
Double-click Prop 3 Days to edit its properties.
Under Propagator, make sure that NearEarth is selected
Under Parameter, replace MAVEN.ElapsedSeconds with MAVEN.ElapsedDays.
Under Condition, replace 0.0 with 3.
Click OK to save these changes.
Figure 50. 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.
85
Tutorials
Mars B-Plane Targeting
2.
3.
4.
5.
Under Propagator, replace NearEarth with DeepSpace.
Under Parameter, replace MAVEN.ElapsedSeconds with MAVEN.ElapsedDays.
Under Condition, replace 0.0 with 12.
Click OK to save these changes.
Figure 51. Prop 12 Days to TCM Command Configuration
Configure the Vary TCM.V Command
1.
2.
3.
4.
5.
6.
7.
86
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.
In the Initial Value box, type 1e-005.
In the Perturbation box, type 0.00001.
In the Lower box, type -10e300.
In the Upper box, type 10e300.
In the Max Step box, type 0.002.
Click OK to save these changes.
Mars B-Plane Targeting
Tutorials
Figure 52. Vary TCM.V Command Configuration
Configure the Vary TCM.N Command
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.
1.
87
Tutorials
Mars B-Plane Targeting
Figure 53. Vary TCM.N Parameter Selection
Figure 54. Vary TCM.N Command Configuration
Configure the Vary TCM.B Command
1.
88
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.
Mars B-Plane Targeting
Tutorials
Next to Variable, click the Edit button.
Under Object List, click TCM.
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.
2.
3.
4.
Figure 55. Vary TCM.B Parameter Selection
89
Tutorials
Mars B-Plane Targeting
Figure 56. 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 57. Apply TCM Command Configuration
Configure the Prop 280 Days Command
1.
2.
3.
4.
5.
90
Double-click Prop 280 Days to edit its properties.
Under Propagator, replace NearEarth with DeepSpace.
Under Parameter, replace MAVEN.ElapsedSeconds with MAVEN.ElapsedDays.
Under Condition, replace 0.0 with 280.
Click OK to save these changes.
Mars B-Plane Targeting
Tutorials
Figure 58. Prop 280 Days Command Configuration
Configure the Prop to Mars Periapsis Command
1.
2.
3.
4.
Double-click Prop to Mars Periapsis to edit its properties.
Under Propagator, replace NearEarth with NearMars.
Under Parameter, replace MAVEN.ElapsedSeconds with MAVEN.Mars.Periapsis.
Click OK to save these changes.
Figure 59. Prop to Mars Periapsis Command Configuration
91
Tutorials
Mars B-Plane Targeting
Configure the Achieve BdotT Command
1.
2.
3.
4.
5.
6.
7.
8.
Double-click Achieve BdotT to edit its properties.
Next to Goal, click the Edit button.
In the Object Properties list, click BdotT.
Under Coordinate System, select MarsInertial and double-click on BdotT.
Click OK to close the ParameterSelectDialog window.
In the Value box, type 0.
In the Tolerance box, type 0.00001.
Click OK to save these changes.
Figure 60. Achieve BdotT Command Configuration
Configure the Achieve BdotR Command
1.
2.
3.
4.
5.
6.
7.
8.
92
Double-click Achieve BdotR to edit its properties.
Next to Goal, click the Edit button.
In the Object Properties list, click BdotR.
Under Coordinate System, select MarsInertial and double-click on BdotR.
Click OK to close the ParameterSelectDialog window.
In the Value box, type -7000.
In the Tolerance box, type 0.00001.
Click OK to save these changes.
Mars B-Plane Targeting
Tutorials
Figure 61. 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.
93
Tutorials
Mars B-Plane Targeting
Figure 62. 3D View of departure hyperbolic trajectory (EarthView)
94
Mars B-Plane Targeting
Tutorials
Figure 63. 3D View of heliocentric transfer trajectory (SolarSystemView)
95
Tutorials
Mars B-Plane Targeting
Figure 64. 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.
2.
3.
4.
96
In the Mission tree, double-click Target desired B-plane Coordinates to edit its properties.
Click Apply Corrections.
Click OK to save these changes.
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.
Mars B-Plane Targeting
5.
Tutorials
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.
2.
In the Mission tree, right-click Apply TCM, and click on Command Summary.
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
3.
Element 3: -0.0006747125434 km/s
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
4.
Mass change: -6.3128738639690 kg
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.
2.
3.
In the Mission tree, right-click Prop to Mars Periapsis, and click on Command Summary.
Under Coordinate System, select MarsInertial.
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 65 illustrates the configuration of the Mission tree after you have completed the steps in this section. Notice that in Figure 65, the second Target sequence is created after the first Target sequence. We’ll
discuss the second Target sequence after it has been created.
97
Tutorials
Mars B-Plane Targeting
Figure 65. Mission Sequence showing first and second Target sequences
To create the second Target sequence:
1.
2.
3.
4.
5.
6.
7.
8.
Click on the Mission tab to show the Mission tree.
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.
Right-click Target2 and click Rename.
Type Mars Capture and click OK.
Right-click Mars Capture, point to Append, and click Vary. A new command called Vary4
will be created.
Right-click Vary4 and click Rename.
In the Rename box, type Vary MOI.V and click OK.
Complete the Target sequence by appending the commands in Table 14.
Table 14. Additional Second Target Sequence Commands
98
Command
Name
Maneuver
Apply MOI
Propagate
Prop to Mars Apoapsis
Achieve
Achieve RMAG
Mars B-Plane Targeting
Tutorials
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.
2.
3.
4.
5.
6.
7.
8.
In the Mission tree, right-click End Mars Capture, point to Insert After, and click Propagate. A new Propagate6 command will appear.
Right-click Propagate6 and click Rename.
Type Prop for 1 day and click OK.
Double-click Prop for 1 day to edit its properties.
Under Propagator, replace NearEarth with NearMars.
Under Parameter, replace MAVEN.ElapsedSeconds with MAVEN.ElapsedDays.
Under Condition, replace the value 0.0 with 1.
Click OK to save these changes
Figure 66. Prop for 1 day Command Configuration
99
Tutorials
Mars B-Plane Targeting
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.
2.
3.
Double-click Mars Capture to edit its properties.
In the ExitMode list, click SaveAndContinue. This instructs GMAT to save the final solution
of the targeting problem after you run it.
Click OK to save these changes
Figure 67. Mars Capture Command Configuration
Configure the Vary MOI.V Command
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.
1.
100
Mars B-Plane Targeting
Tutorials
Figure 68. Vary MOI Parameter Selection
Figure 69. Vary MOI Command Configuration
Configure the Apply MOI Command
1.
2.
3.
Double-click Apply MOI to edit its properties.
In the Burn list, click MOI.
Click OK to save these changes.
101
Tutorials
Mars B-Plane Targeting
Figure 70. Apply MOI Command Configuration
Configure the Prop to Mars Apoapsis Command
1.
2.
3.
4.
Double-click Prop to Mars Apoapsis to edit its properties.
Under Propagator, replace NearEarth with NearMars.
Under Parameter, replace MAVEN.ElapsedSeconds with MAVEN.Mars.Apoapsis.
Click OK to save these changes.
Figure 71. Prop to Mars Apoapsis Command Configuration
Configure the Achieve RMAG Command
1.
2.
3.
4.
102
Double-click Achieve RMAG to edit its properties.
Next to Goal, click the Edit button.
In the Object Properties list, click RMAG.
Under Central Body, select Mars and double-click on RMAG.
Mars B-Plane Targeting
5.
6.
7.
Tutorials
Click OK to close the ParameterSelectDialog window.
In the Value box, type 12000.
Click OK to save these changes.
Figure 72. 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 oneiteration. 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.
103
Tutorials
Mars B-Plane Targeting
Figure 73. 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.
104
In the Mission tree, double-click Mars Capture to edit its properties.
Mars B-Plane Targeting
2.
3.
4.
Tutorials
Click Apply Corrections.
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.
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.
2.
In the Mission tree, right-click Apply MOI, and click on Command Summary.
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
3.
Element 3: 0.0000000000000 km/s
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.
2.
3.
In the Mission tree, right-click Achieve RMAG, and click on Command Summary.
Under Coordinate System, select MarsInertial.
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
105
106
Tutorials
Optimal Lunar Flyby using Multiple
Shooting
Audience
Length
Prerequisites
Script File
Advanced
90 minutes
Complete Simulating an Orbit, Simple Orbit Transfer, Mars B-Plane Targeting tutorial and take GMAT Fundamentals training course or watch videos
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
107
Tutorials
Optimal Lunar Flyby using Multiple
Shooting
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 74. View of Lunar Flyby from Normal to Earth Equator
108
Optimal Lunar Flyby using Multiple
Shooting
Tutorials
Figure 75. 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 76. 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.
2.
3.
4.
5.
6.
7.
Create a Moon-centered coordinate system.
Create 5 spacecraft required for modeling segments.
Create an Earth-centered and a Moon-centered propagator.
Create an impulsive maneuver.
Create many user variables for use in the script.
Create A VF13ad optimizer.
Create plots for tracking the optimization process.
109
Tutorials
Optimal Lunar Flyby using Multiple
Shooting
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.
2.
3.
4.
5.
Run the sequence and analyze the initial guess.
Run the optimizer satisfying only the patch point constraints.
Turn on the mission orbit constraints and find a feasible solution.
Use the feasible solution as the initial guess and find an optimal solution.
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
110
Optimal Lunar Flyby using Multiple
Shooting
Tutorials
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
satTOI.CoordinateSystem
= TAIModJulian
= 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
satMOI_Backward.CoordinateSystem
= TAIModJulian
= EarthMJ2000Eq
% MOI control point
Create Spacecraft satMOI_Forward
satMOI_Forward.DateFormat
satMOI_Forward.CoordinateSystem
= TAIModJulian
= 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
%----------------------------------------------------
111
Tutorials
Optimal Lunar Flyby using Multiple
Shooting
Create ForceModel NearEarthForceModel
NearEarthForceModel.CentralBody
NearEarthForceModel.PrimaryBodies
NearEarthForceModel.PointMasses
NearEarthForceModel.SRP
NearEarthForceModel.GravityField.Earth.Degree
NearEarthForceModel.GravityField.Earth.Order
=
=
=
=
=
=
Earth
{Earth}
{Luna, Sun}
On
8
8
Create ForceModel NearMoonForceModel
NearMoonForceModel.CentralBody
NearMoonForceModel.PointMasses
NearMoonForceModel.Drag
NearMoonForceModel.SRP
=
=
=
=
Luna
{Luna, Earth, Sun}
None
On
Create Propagator NearEarthProp
NearEarthProp.FM = NearEarthForceModel
NearEarthProp.Type
NearEarthProp.InitialStepSize
NearEarthProp.Accuracy
NearEarthProp.MinStep
NearEarthProp.MaxStep
=
=
=
=
=
PrinceDormand78
60
1e-11
0.0
86400
Create Propagator NearMoonProp
NearMoonProp.FM
NearMoonProp.Type
NearMoonProp.InitialStepSize
NearMoonProp.Accuracy
NearMoonProp.MinStep
NearMoonProp.MaxStep
=
=
=
=
=
=
NearMoonForceModel
PrinceDormand78
60
1e-11
0
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
112
Optimal Lunar Flyby using Multiple
Shooting
Tutorials
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 toiEpoch 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
NLPOpt.ReportStyle
NLPOpt.ReportFile
NLPOpt.MaximumIterations
NLPOpt.Tolerance
NLPOpt.UseCentralDifferences
NLPOpt.FeasibilityTolerance
=
=
=
=
=
=
=
true
Normal
'VF13adVF13ad1.data'
200
1e-004
false
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 coor113
Tutorials
Optimal Lunar Flyby using Multiple
Shooting
dinate 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.
%---------------------------------------------------% Configure plots, reports, etc.
%---------------------------------------------------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
PositionError.UpperLeft
PositionError.Size
PositionError.RelativeZOrder
PositionError.XVariable
PositionError.YVariables
PositionError.ShowGrid
PositionError.ShowPlot
114
=
=
=
=
=
=
=
=
All
[ 0.02318840579710145 0.4358208955223881 ];
[ 0.4594202898550724 0.5283582089552239 ];
378
loopIdx
{errorPos1, errorPos2}
true
true
Optimal Lunar Flyby using Multiple
Shooting
Tutorials
Create XYPlot VelocityError
VelocityError.SolverIterations
VelocityError.UpperLeft
VelocityError.Size
VelocityError.RelativeZOrder
VelocityError.XVariable
VelocityError.YVariables
VelocityError.ShowGrid
VelocityError.ShowPlot
Create XYPlot OrbitDimErrors
OrbitDimErrors.SolverIterations
OrbitDimErrors.UpperLeft
=
OrbitDimErrors.Size
=
OrbitDimErrors.RelativeZOrder =
OrbitDimErrors.XVariable
=
OrbitDimErrors.YVariables
=
OrbitDimErrors.ShowGrid
=
OrbitDimErrors.ShowPlot
=
=
=
=
=
=
=
=
=
Create XYPlot IncError
IncError.SolverIterations
IncError.UpperLeft
IncError.Size
IncError.RelativeZOrder
IncError.YVariables
IncError.XVariable
IncError.ShowGrid
IncError.ShowPlot
=
=
=
=
=
=
=
=
All
[ 0.02463768115942029 0.01194029850746269 ];
[ 0.4565217391304348 0.4208955223880597 ];
410
loopIdx
{errorVel1, errorVel2}
true
true
= All
[ 0.4960127591706539 0.5337301587301587 ];
[ 0.481658692185008 0.4246031746031746 ];
347
loopIdx
{errorMOIRadApo, errorMOIRadPer}
true
true
All
[ 0.4953586497890296 0.01306240928882438 ];
[ 0.479324894514768 0.5079825834542816 ];
382
{errorMOIInclination}
loopIdx
true
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 =
debugData.Precision
=
debugData.WriteHeaders
=
debugData.LeftJustify
=
debugData.ZeroFill
=
debugData.ColumnWidth
=
debugData.WriteReport
=
Current
16
Off
On
Off
20
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
115
Tutorials
Optimal Lunar Flyby using Multiple
Shooting
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'
% Robust intial guess but not feasible
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
116
Optimal Lunar Flyby using Multiple
Shooting
Tutorials
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
= toiEpoch
% ref. epoch for time quantities
EndScript
% The optimization loop
Optimize 'Optimize Flyby' NLPOpt ...
117
Tutorials
Optimal Lunar Flyby using Multiple
Shooting
{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(toiEpoch = toiEpoch, {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
satMOI_Backward.Epoch.TAIModJulian
satFlyBy_Forward.Epoch.TAIModJulian
patchOneEpoch
patchTwoEpoch
=
=
=
=
=
toiEpoch
moiEpoch
flybyEpoch
refEpoch + patchOneElapsedDays
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
118
Optimal Lunar Flyby using Multiple
Shooting
Tutorials
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})
119
Tutorials
Optimal Lunar Flyby using Multiple
Shooting
% Initialize spacecraft and do some reporting
satFlyBy_Backward = satFlyBy_Forward
satMOI_Forward
= satMOI_Backward
deltaTimeFlyBy
= flybyEpoch - toiEpoch
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
120
Optimal Lunar Flyby using Multiple
Shooting
Tutorials
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}
PenUp EarthView % The next three lines handle discontinuity in plots
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
PenUp EarthView % The next three lines handle discontinuity in plots
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 discontinuity in plots
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 + ...
121
Tutorials
Optimal Lunar Flyby using Multiple
Shooting
(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/others on segments after propagation
errorMOIInclination = satMOI_Forward.INC - conMOIInclination
%NonlinearConstraint NLPOpt(satMOI_Forward.EarthMJ2000Eq.INC = ...
% conMOIInclination)
% Propagate satMOI_Forward to apogee
PenUp EarthView
% The next three lines handle discontinuity in plots
Propagate NearEarthProp(satMOI_Forward)
PenDown EarthView
122
Optimal Lunar Flyby using Multiple
Shooting
Tutorials
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.
2.
3.
4.
5.
Run the script configuration and verify your configuration.
Run the mission applying only the patch point constraints to provide a smooth trajectory.
Run the mission with all constraints applied generating an optimal solution.
Run the mission with an alternative initial guess.
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.
123
Tutorials
Optimal Lunar Flyby using Multiple
Shooting
Figure 77. 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.
124
Optimal Lunar Flyby using Multiple
Shooting
Tutorials
Figure 78. Alternate View (1) of Discontinuous Trajectory
Figure 79. 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.
125
Tutorials
Optimal Lunar Flyby using Multiple
Shooting
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 80. 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)
126
Optimal Lunar Flyby using Multiple
Shooting
Tutorials
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 81. 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
127
Tutorials
Optimal Lunar Flyby using Multiple
Shooting
Delta
Delta
Delta
Delta
Delta
Delta
satMOI_Backward.EarthMJ2000Eq.Z = 0.0063349630509
satMOI_Backward.EarthMJ2000Eq.VX = -7.5196416871e-008
satMOI_Backward.EarthMJ2000Eq.VY = -7.48570442854e-008
satMOI_Backward.EarthMJ2000Eq.VZ = -6.01668809219e-009
satMOI_Forward.EarthMJ2000Eq.INC = -1.25488952563e-010
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
128
Optimal Lunar Flyby using Multiple
Shooting
Tutorials
Figure 82. 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.
129
130
Tutorials
Mars B-Plane Targeting Using GMAT
Functions
Audience
Length
Prerequisites
Script and function Files
Advanced
75 minutes
Complete Simulating an Orbit, Simple Orbit Transfer, Mars BPlane Targeting and a basic understanding of B-Planes and
their usage in targeting is required.
Tut_UsingGMATFunctions.script,
TargeterInsideFunction.gmf
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 83 and Figure 84 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 BPlane. Once the spacecraft gets close to Mars, then an orbit insertion maneuver can be
performed to capture into Mars orbit.
Figure 83. Geometry of the B-Plane as seen
from a viewpoint perpendicular to the B-Plane
131
Tutorials
Mars B-Plane Targeting Using
GMAT Functions
Figure 84. 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 with the emphasis of how to use
GMAT functions. 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 Binormal (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 entire first target sequence will be created inside a GMAT function.
In the Mission tree, this function will be called through GMAT's CallGmatFunction command.
Additionally, we'll go ahead and declare pertinent objects (e.g. spacecraft, force models, subscribers,
impulsive burns etc.) as global in both the main script and inside the function through GMAT's
Global command.
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. Unlike the first target sequence, the second target sequence will not be created inside a function.
The purpose behind this tutorial is to demonstrate how GMAT functions are created, populated,
called-upon and used as part of practical mission design. In this tutorial, we'll deliberately put the
entire first target sequence inside a GMAT function. Next in the Mission tree, we'll call and execute
the function, then continue with the design of the second target sequence outside of the function.
Key objects such as the spacecraft, force models, subscribers etc. will be declared global in order
132
Mars B-Plane Targeting Using
GMAT Functions
Tutorials
to assure continuous flow of data is plotted and reported to all the subscribers. The basic steps of
this tutorial are:
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 single ReportFile resource that will be used in reporting data.
8. Create and configure three CoordinateSystems: Earth, Sun and Mars centered.
9. Create and configure single GmatFunction resource that will be called and executed in the
Mission tree.
10. Create first Target sequence inside the GMAT function. This sequence will be used to target
BdotT and BdotR components of the B-vector.
11. Create second Target sequence to implement MOI by targeting position magnitude at apoapsis.
12. Run the mission and analyze the results.
1.
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.
2.
3.
4.
5.
In the Resources tree, right-click the Hardware folder, point to Add and click ChemicalTank. A new resource called ChemicalTank1 will be created.
Right-clickChemicalTank1 and click Rename.
In theRename box, type MainTank and click OK.
Double click onMainTank to edit its properties.
Set the values shown in the table below.
Table 15. MainTank settings
Field
Value
Fuel Mass
1718
Fuel Density
1000
Pressure
5000
Volume
2
133
Tutorials
Mars B-Plane Targeting Using
GMAT Functions
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.
2.
3.
4.
In the Resources tree, under Spacecraft folder, right-click DefaultSC and click Rename.
In the Rename box, type MAVEN and click OK.
Double-click on MAVEN to edit its properties. Make sure Orbit tab is selected.
Set the values shown in the table below.
Table 16. MAVEN settings
5.
6.
7.
8.
Field
Value
Epoch Format
UTCGregorian
Epoch
18 Nov 2013 20:26:24.315
Coordinate System
EarthMJ2000Eq
State Type
Keplerian
SMA under Elements
-32593.21599272796
ECC under Elements
1.202872548116185
INC under Elements
28.80241266404142
RAAN under Elements
173.9693759331483
AOP under Elements
240.9696529532764
TA under Elements
359.9465533778069
Click on Tanks tab now.
Under Available Tanks, you'll see MainTank. This is the fuel tank that we created earlier.
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.
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.
2.
3.
134
In the Resources tree, under the Burns folder, right-click DefaultIB and click Rename.
In the Rename box, type TCM, an acronym for Trajectory Correction Maneuver and click
OK to edit its properties.
Double-Click TCM to edit its properties.
Mars B-Plane Targeting Using
GMAT Functions
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
Tutorials
Check Decrement Mass under Mass Change.
For Tank field under Mass Change, select MainTank from drop down menu.
Click OK to save these changes.
Right-click theBurns folder, point to Add, and click ImpulsiveBurn. A new resource called
ImpulsiveBurn1 will be created.
Rename the new ImpulsiveBurn1 resource to MOI, an acronym for Mars Orbit Insertion
and click OK.
Double-click MOI to edit its properties.
For Origin field under Coordinate System, select Mars.
Check Decrement Mass under Mass Change.
For Tank field under Mass Change, select MainTank from the drop down menu.
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.
2.
3.
4.
In the Resources tree, under the Propagators folder, right-click DefaultProp and click Rename.
In the Rename box, type NearEarth and click OK.
Double-click on NearEarth to edit its properties.
Set the values shown in the table below.
Table 17. NearEarth settings
5.
6.
7.
8.
9.
Field
Value
Initial Step Size under Integrator
600
Accuracy under Integrator
1e-013
Min Step Size under Integrator
0
Max Step Size under Integrator
600
Model under Gravity
JGM-2
Degree under Gravity
8
Order under Gravity
8
Atmosphere Model under Drag
None
Point Masses under Force Model
Add Luna and Sun
Use Solar Radiation Pressure under Force Model
Check this field
Click on OK to save these changes.
Right-click the Propagators folder and click Add Propagator. A new resource called Propagator1 will be created.
Rename the new Propagator1 resource to DeepSpace and click OK.
Double-click DeepSpace to edit its properties.
Set the values shown in the table below.
135
Tutorials
Mars B-Plane Targeting Using
GMAT Functions
Table 18. DeepSpace settings
Field
Value
Type under Integrator
PrinceDormand78
Initial Step Size under Integrator
600
Accuracy under Integrator
1e-012
Min Step Size under Integrator
0
Max Step Size under Integrator
864000
Central Body under Force Model
Sun
Primary Body under Force Model
None
Point Masses under Force Model
Add Earth, Luna, Sun, Mars,
Jupiter, Neptune, Saturn,
Uranus, Venus
Use Solar Radiation Pressure under Force Model
Check 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 19. NearMars settings
Field
Value
Type under Integrator
PrinceDormand78
Initial Step Size under Integrator
600
Accuracy under Integrator
1e-012
Min Step Size under Integrator
0
Max Step Size under Integrator
86400
Central Body under Force Model
Mars
Primary Body under Force Model
Mars
Model under Gravity
Mars-50C
Degree under Gravity
8
Order under Gravity
8
Atmosphere Model under Drag
None
Point Masses under Force Model
Add Sun
Use Solar Radiation Pressure under Force Model
Check this field
15. Click OK to save the changes.
136
Mars B-Plane Targeting Using
GMAT Functions
Tutorials
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.
2.
3.
In the Resources tree, expand the Solvers folder if it isn’t already.
Right-click the Boundary Value Solvers folder, point to Add, and click DifferentialCorrector. A new resource called DC1 will be created.
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.
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.
1.
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.
2.
3.
4.
5.
In the Resources tree, under Output folder, right-click DefaultOrbitView and click Rename.
In the Rename box, type EarthView and click OK.
In the Output folder, delete DefaultGroundTrackPlot.
Double-click EarthView to edit its properties.
Set the values shown in the table below.
Table 20. EarthView settings
Field
Value
View Scale Factor under View Definition
4
View Point Vector boxes, under View Definition
0, 0, 30000
137
Tutorials
Mars B-Plane Targeting Using
GMAT Functions
Click OK to save these changes.
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.
6.
7.
Table 21. SolarSystemView settings
Field
Value
From Celestial Object under View Object, add following Mars, Sun (Do not remove
objects to Selected Celestial Object box
Earth)
Coordinate System under View Definition
SunEcliptic
View Point Reference under View Definition
Sun
View Point Vector boxes, under View Definition
0, 0, 5e8
View Direction under View Definition
Sun
Coordinate System under View Up Definition
SunEcliptic
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 22. MarsView settings
Field
Value
From Celestial Object under View Object, add following Mars (You don’t have to reobject to Selected Celestial Object box
move Earth)
Coordinate System under View Definition
MarsInertial
View Point Reference under View Definition
Mars
View Point Vector boxes, under View Definition
22000, 22000, 0
View Direction under View Definition
Mars
Coordinate System under View Up Definition
MarsInertial
16. Click OK to save the changes.
Create single Report File
We’ll need a single ReportFile resource for this tutorial that we'll use to report data to.
1.
138
Right-click the Output folder, point to Add, and click ReportFile. A new resource called
ReportFile1 will be created.
Mars B-Plane Targeting Using
GMAT Functions
2.
3.
4.
5.
Tutorials
Rename the new ReportFile1 resource to rf and click OK.
Double-Click rf to edit its properties.
Empty the Parameter List by clicking on the Edit button.
Click OK to save these changes.
Create a GMAT Function
We’ll need a single GMATFunction resource for this tutorial. The first target sequence will be
implemented inside this function.
1.
2.
3.
4.
Right-click the Functions folder, point to Add, point to GMAT Function and click New.
A new GMAT function panel will open. Type the following name for the function TargeterInsideFunction and click OK to save these changes.
Now open TargeterInsideFunction resource and paste the below shown first targeter sequence snippet into this function.
After pasting of the below snippet is done, click on Save As button and save your function.
After saving your function, close TargeterInsideFunction resource by clicking on the Close
button.
% Target Desired B-Plane Coordinates in this function:
function TargeterInsideFunction()
BeginMissionSequence
Global 'Make Objects Global' MAVEN DeepSpace_ForceModel DefaultDC ...
EarthView MainTank MarsView MOI NearEarth_ForceModel ...
NearMars_ForceModel rf SolarSystemView TCM
Target 'Target B-plane coordinates' DefaultDC {SolveMode = Solve, ...
ExitMode = SaveAndContinue}
Propagate 'Prop 3 days' NearEarth(MAVEN) {MAVEN.ElapsedDays = 3}
Propagate 'Prop 12 Days to TCM' DeepSpace(MAVEN) {MAVEN.ElapsedDays = 12}
Vary 'Vary TCM.V' DefaultDC(TCM.Element1 = 0.001, ...
{Perturbation = 0.00001, MaxStep = 0.002})
Vary 'Vary TCM.N' DefaultDC(TCM.Element2 = 0.001, ...
{Perturbation = 0.00001, MaxStep = 0.002})
Vary 'Vary TCM.B' DefaultDC(TCM.Element3 = 0.001, ...
{Perturbation = 0.00001, MaxStep = 0.002})
Maneuver 'Apply TCM' TCM(MAVEN)
Propagate 'Prop 280 Days' DeepSpace(MAVEN) {MAVEN.ElapsedDays = 280}
Propagate 'Prop to Mars Periapsis' NearMars(MAVEN) {MAVEN.Mars.Periapsis}
Achieve 'Achieve BdotT' DefaultDC(MAVEN.MarsInertial.BdotT = 0, ...
{Tolerance = 0.00001})
Achieve 'Achieve BdotR' DefaultDC(MAVEN.MarsInertial.BdotR = -7000, ...
{Tolerance = 0.00001})
EndTarget;
139
Tutorials
Mars B-Plane Targeting Using
GMAT Functions
% Report MAVEN parameters to global 'rf' :
Report 'Report Parameters' rf MAVEN.UTCGregorian TCM.Element1 ...
TCM.Element2 TCM.Element3 MAVEN.MarsInertial.BdotT ...
MAVEN.MarsInertial.BdotR MAVEN.MarsInertial.INC
Reminder that the first target sequence will target desired B-Plane coordinates which will get the
spacecraft MAVEN close to Mars. Note that we have declared all the pertinent objects as global
at the beginning of the function. These same objects will also be declared global in the Mission
Sequence as well. Notice that in this first target sequence, spacecraft MAVEN props for 3 days
using NearEarth propagator. Next using the DeepSpace propagator, we propagate for 12 days
and execute TCM impulsive maneuver. Again using the DeepSpace propagator, we propagate for
another 280 days and finally propagate to Mars Periapsis. The desired constraints of the B-Plane
coordinates are to be met at the Mars periapsis. The three components of the TCM impulsive burn
are the controls that will help us achieve these two constraints. Note that the tolerances on the two
B-Plane constraints are relatively tight.
Configure the Mission Sequence
Now we are ready to configure the Mission Sequence. We will first insert a Global command
and declare the same objects as global that were declared global inside the TargeterInsideFunction function. Next we'll insert CallGmatFunction command which will call and initiate our TargeterInsideFunction function that contains our first target sequence. The first target sequence will
solve for the TCM maneuver values required to achieve BdotT and BdotR components of the Bvector. 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.
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:
Create Commands to Initiate the First Target Sequence
Now create the commands necessary to perform the first Target sequence. Figure 85 illustrates the
configuration of the Mission tree after you have completed the steps in this section.
Figure 85. Mission Sequence for the First Target sequence
Do following steps to set-up for the first Target sequence:
1.
2.
140
Click on the Mission tab to show the Mission tree.
You’ll see that there already exists a Propagate1 command. We need to delete this command
Mars B-Plane Targeting Using
GMAT Functions
3.
4.
5.
6.
7.
8.
9.
Tutorials
Right-click on Propagate1 command and click Delete.
Right-click on Mission Sequence folder, point to Append, and click Global. A new command
called Global1 will be created.
Right-click Global1 and click Rename. In the Rename box, type Make Objects Global and
click OK.
Right-click on Mission Sequence folder, point to Append, and click CallGmatFunction. A
new command called CallGmatFunction1 will be created.
Right-click CallGmatFunction1 and click Rename. In the Rename box, type Target Desired
B-Plane Coord. From Inside Function and click OK.
Right-click on Mission Sequence folder, point to Append, and click Report. A new command
called Report1 will be created.
Right-click Report1 and click Rename. In the Rename box, type Report Parameters and
click OK.
Configure the Mission Tree to Run 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 Make Objects Global Command
1.
2.
3.
Double-click Make Objects Global to edit its properties.
Under Please Select Objects to Make Global check all the available object and make all
available objects as global. Recall that same objects were declared as global inside TargeterInsideFunction function as well.
Click OK to save these changes.
141
Tutorials
Mars B-Plane Targeting Using
GMAT Functions
Figure 86. Make Objects Global Command Configuration
Configure the Target Desired B-Plane Coord. From Inside Function
Command
1.
2.
3.
142
Double-click Target Desired B-Plane Coord. From Inside Function to edit its properties.
Under Function, select TargeterInsideFunction from drop down menu. In this particular
example, since we're not passing any input(s) or receiving any output(s) to and from the function, hence we won't be editing Input/Output menu.
Click OK to save these changes.
Mars B-Plane Targeting Using
GMAT Functions
Tutorials
Figure 87. Target Desired B-Plane Coord. From
Inside Function Command Configuration
Configure the Report Parameters Command
1.
2.
3.
4.
Double-click Report Parameters to edit its properties.
Under ReportFile, make sure rf is selected from the from drop down menu.
Under Parameter List click on View. This opens up a new ParameterSelectDialog panel.
Make sure to select the parameters that are shown in the below Report Parameters screenshot
image.
Click OK to save these changes.
143
Tutorials
Mars B-Plane Targeting Using
GMAT Functions
Figure 88. Report Parameters 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.
144
Mars B-Plane Targeting Using
GMAT Functions
Tutorials
Figure 89. 3D View of departure hyperbolic trajectory (EarthView)
Figure 90. 3D View of heliocentric transfer trajectory (SolarSystemView)
145
Tutorials
Mars B-Plane Targeting Using
GMAT Functions
Figure 91. 3D View of approach hyperbolic
trajectory. MAVEN stopped at periapsis (MarsView)
Now go to the Output tree and open rf. Recall that rf was declared as a global object both inside
the function and in the main script. Notice that both the controls (i.e. TCM burn elements) and
constraints (i.e. BdotT, BdotR) are reported as well as MAVEN inclination relative to MarsInertial
coordinate system. The desired constraints that were set in the first targeter sequence have been
successfully achieved.
Now go back to Mission tree and right click on Target Desired B-Plane Coord. From Inside
Function command and click on Command Summary option. Under Coordinate System drop
down menu, select MarsIntertial and study the command summary. This command summary corresponds to the very last Propagate command (i.e. 'Prop to Mars Periapsis') from inside the GMAT
function. Under Hyperbolic Parameters, notice the values of BdotT and BdotR. These are the
constraints that have been achieved on the very last 'Prop to Mars Periapsis' Propagate command
from the first targeter which was set up inside the GMAT function.
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 which was defined inside the GMAT function
TargeterInsideFunction.
Now let’s create the commands necessary to perform the second Target sequence. Figure 92 illustrates the configuration of the Mission tree after you have completed the steps in this section. Notice that in Figure 92, the second Target sequence is created after the first Target sequence which
was called via the CallGmatFunction command. We’ll discuss the second Target sequence after
it has been created.
146
Mars B-Plane Targeting Using
GMAT Functions
Tutorials
Figure 92. Mission Sequence showing first and second Target sequences
To create the second Target sequence:
1.
2.
3.
4.
5.
6.
7.
8.
Click on the Mission tab to show the Mission tree.
In the Mission tree, right-click on Mission Sequence folder, point to Append, and click
Target. This will insert two separate commands: Target1 and EndTarget1.
Right-click Target1 and click Rename.
Type Mars Capture and click OK.
Right-click Mars Capture, point to Append, and click Vary. A new command called Vary4
will be created.
Right-click Vary4 and click Rename.
In the Rename box, type Vary MOI.V and click OK.
Complete the Target sequence by appending the commands in Table 23.
Table 23. Additional Second Target Sequence Commands
Command
Name
Maneuver
Apply MOI
Propagate
Prop to Mars Apoapsis
Achieve
Achieve RMAG
147
Tutorials
Mars B-Plane Targeting Using
GMAT Functions
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.
2.
3.
4.
5.
6.
7.
8.
In the Mission tree, right-click End Mars Capture, point to Insert After, and click Propagate. A new Propagate3 command will appear.
Right-click Propagate6 and click Rename.
Type Prop for 1 day and click OK.
Double-click Prop for 1 day to edit its properties.
Under Propagator, replace NearEarth with NearMars.
Under Parameter, replace MAVEN.ElapsedSeconds with MAVEN.ElapsedDays.
Under Condition, replace the value 0.0 with 1.
Click OK to save these changes
Figure 93. Prop for 1 day Command Configuration
148
Mars B-Plane Targeting Using
GMAT Functions
Tutorials
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.
2.
3.
Double-click Mars Capture to edit its properties.
In the ExitMode list, click SaveAndContinue. This instructs GMAT to save the final solution
of the targeting problem after you run it.
Click OK to save these changes
Figure 94. Mars Capture Command Configuration
Configure the Vary MOI.V Command
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.
1.
149
Tutorials
Mars B-Plane Targeting Using
GMAT Functions
Figure 95. Vary MOI Parameter Selection
Figure 96. Vary MOI Command Configuration
Configure the Apply MOI Command
1.
2.
3.
150
Double-click Apply MOI to edit its properties.
In the Burn list, click MOI.
Click OK to save these changes.
Mars B-Plane Targeting Using
GMAT Functions
Tutorials
Figure 97. Apply MOI Command Configuration
Configure the Prop to Mars Apoapsis Command
1.
2.
3.
4.
Double-click Prop to Mars Apoapsis to edit its properties.
Under Propagator, replace NearEarth with NearMars.
Under Parameter, replace MAVEN.ElapsedSeconds with MAVEN.Mars.Apoapsis.
Click OK to save these changes.
Figure 98. Prop to Mars Apoapsis Command Configuration
Configure the Achieve RMAG Command
1.
2.
3.
4.
Double-click Achieve RMAG to edit its properties.
Next to Goal, click the Edit button.
In the Object Properties list, click RMAG.
Under Central Body, select Mars and double-click on RMAG.
151
Tutorials
Mars B-Plane Targeting Using
GMAT Functions
5.
6.
7.
Click OK to close the ParameterSelectDialog window.
In the Value box, type 12000.
Click OK to save these changes.
Figure 99. 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 first after
a few 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.
152
Mars B-Plane Targeting Using
GMAT Functions
Tutorials
Figure 100. 3D view of Mars Capture
orbit after MOI maneuver (MarsView)
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.
2.
In the Mission tree, right-click Apply MOI, and click on Command Summary.
Scroll down and under Maneuver Summary heading, values for delta-V vector are:
Delta V Vector:
Element 1: -1.6032580309280 km/s
Element 2: 0.0000000000000 km/s
3.
Element 3: 0.0000000000000 km/s
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.6032580309280 km/s
Mass change: -1075.9520121897 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.
2.
In the Mission tree, right-click Achieve RMAG, and click on Command Summary.
Under Coordinate System, select MarsInertial.
153
Tutorials
Mars B-Plane Targeting Using
GMAT Functions
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.00000085377 deg
RMAG = 12000.017390989 km
154
Tutorials
Finding Eclipses and Station Contacts
Audience
Length
Prerequisites
Script File
Beginner
30 minutes
Complete Simple Orbit Transfer
Tut_EventLocation.script
Objective and Overview
In this tutorial we will modify an existing mission to add eclipse and station contact detection using
the EclipseLocator and ContactLocator resources. We will start with the completed Simple Orbit
Transfer mission and modify it to add these event reports.
The basic steps of this tutorial are:
1.
2.
3.
4.
5.
6.
Load the Simple Orbit Transfer mission.
Configure GMAT for event location.
Add and configure an EclipseLocator to report eclipses.
Run the mission and analyze the eclipse report.
Add and configure a GroundStation and a ContactLocator to report contact times.
Run the mission and analyze the contact report.
Load the Mission
For this tutorial, we will start with a preexisting mission created during the Simple Orbit Transfer
tutorial. You can either complete that tutorial prior to this one, or you can load the end result directly,
as shown below.
1.
2.
3.
4.
Open GMAT.
Click Open in the toolbar and navigate to the GMAT samples directory.
Select Tut_SimpleOrbitTransfer.script and click Open.
Click Run ( ) to run the mission.
You should see the following result in the DefaultOrbitView window.
155
Tutorials
Finding Eclipses and Station Contacts
Configure GMAT for Event Location
GMAT's event location subsystem is based on the NAIF SPICE library, which uses its own mechanism for configuration of the solar system. Instead of settings specified in GMAT via CelestialBody
resources like Earth and Luna, SPICE uses "kernel" files that define similar parameters independently. This is discussed in detail in the ContactLocator and EclipseLocator references.
By default, GMAT offers general consistency between both configurations. But, it's useful to verify
that the appropriate parameters are correct, and it's necessary for precise applications.
Verify SolarSystem Configuration
First, let's verify that the SolarSystem resource is configured properly for both configurations.
1.
2.
On the Resources tab, double-click the SolarSystem folder. This will display the SolarSystem
configuration.
Scroll to the end of each input box to see the actual filenames being loaded.
You should see a configuration like this:
156
Finding Eclipses and Station Contacts
Tutorials
Note the following items:
• Ephemeris Source: This is set to use the DE405 planetary ephemeris, the default in GMAT. If
you switch to another ephemeris version, the fields below will update accordingly.
• Ephemeris Filename: This is the DE-format ephemeris file used for propagation and parameter
calculations in GMAT itself.
• SPK Kernel: This is the SPICE SPK file used for planetary ephemeris for SPK propagation and
for event location. Note that this is set consistent with Ephemeris Filename (both DE405)
• Leap Second Kernel: This is the SPICE LSK file used to keep track of leap seconds in the UTC
time system for the SPICE subsystem. This is kept consistent with GMAT's internal leap seconds
file (tai-utc.dat) specified in the GMAT startup file.
• Planetary Constants Kernel: This is the SPICE PCK file used for default configuration for all
the default celestial bodies. This file contains planetary shape and orientation information, similar
to but independent from the settings in GMAT's CelestialBody resources (Earth, Luna, etc.).
These are already configured correctly, so we don't need to make any changes.
Configure CelestialBody Resources
Next, let's configure the Earth model for precise usage with the ContactLocator resource. By default, the Earth size and shape differ by less than 1 m in equatorial and polar radii between the two
subsystems But we can make them match exactly by modifying GMAT's Earth properties.
1.
2.
3.
On the Resources tab, expand the SolarSystem folder.
Double-click Earth to display the Earth configuration.
Note the various configuration options available:
• Equatorial Radius and Flattening define the Earth shape for GMAT itself. PCK Files
lists additional SPICE PCK files to load, in addition to the file shown above in the SolarSys157
Tutorials
Finding Eclipses and Station Contacts
4.
5.
6.
tem Planetary Constants Kernel box. In this case, these files provide high-fidelity Earth
orientation parameters (EOP) data.
• On the Orientation tab, Spice Frame Id indicates the Earth-fixed frame to use for the
SPICE subsystem, and FK Files provides additional FK files that define the frame. In this
case, Earth is using the built-in ITRF93 frame, which is different but very close to GMAT's
EarthFixed coordinate system. See the CoordinateSystem reference for details on that system.
Set Equatorial Radius to 6378.1366.
Set Flattening to 0.00335281310845547.
Click OK.
These two values were taken from the pck00010.tpc file referenced in the SolarSystem configuration. Setting them for Earth ensures that the position of the GroundStation we create later will be
referenced to the exact same Earth definition throughout the mission. Note that the exact position
may still differ between the two based on the different body-fixed frame definition and the different
EOP data sources, but this residual difference is small.
Your Earth panel should look like this after these steps are complete:
Configure and Run the Eclipse Locator
Now we are ready to search for eclipses in our mission. We do this by creating an EclipseLocator
resource that holds the search configuration. Then we can perform a search by running the FindEvents command, but GMAT does this automatically at the end of the mission unless you configure
it otherwise. In this case, we will use the automatic option.
Create and Configure the EclipseLocator
First we create the EclipseLocator:
158
Finding Eclipses and Station Contacts
•
Tutorials
On the Resources tab, right-click the Event Locators folder, point to Add, and click EclipseLocator.
This will result in a new resource called EclipseLocator1.
Next, we need to configure the new resource for our mission:
1.
Double-click EclipseLocator1 to edit the configuration.
Note the following default settings:
2.
• Spacecraft is set to DefaultSC, the name of our spacecraft.
• OccultingBodies is set to Earth and Luna. These are the two bodies that will be searched
for eclipses.
• EclipseTypes is set to search for all eclipse types (umbra or total, penumbra or partial, and
antumbra or annular)
• Run Mode is set to Automatic mode, which means the eclipse search will be run automatically at the end of the mission.
• Use Entire Interval is checked, so the entire mission time span will be searched.
• Light-time delay and stellar aberration are both enabled, so eclipse times will be adjusted
appropriately.
• Step size is set to 10 s. This is the minimum-duration eclipse (or gap between eclipses) that
this locator is guaranteed to find.
Click OK to accept the default settings. They are fine for our purposes.
The final configuration should match the following screenshot.
159
Tutorials
Finding Eclipses and Station Contacts
Run the Mission
Now it's time to run the mission and look at the results.
1.
Click Run ( ) to run the mission.
The eclipse search will take a few seconds. As it progresses, you'll see the following message in
the message window at the bottom of the screen:
2.
3.
Finding events for EclipseLocator EclipseLocator1 ...
Celestial body properties are provided by SPICE kernels.
When the run is complete, click the Output tab to view the available output.
Double-click EclipseLocator1 to view the eclipse report.
You'll see a report that looks similar to this:
160
Finding Eclipses and Station Contacts
Tutorials
Three eclipses were found, all part of a single "total" eclipse event totalling about 35 minutes. A total
event consists of all adjacent and overlapping portions, such as penumbra eclipses occuring adjacent
to umbra eclipses as in this case.
•
Click Close to close the report. The report text is still available as EclipseLocator1.txt
in the GMAT output folder.
Configure and Run the Contact Locator
Finding ground station contact times is a very similar process, but we'll use the ContactLocator
resource instead. First we need to add a GroundStation, then we can configure the locator to find
contact times between it and our spacecraft.
Create and Configure a Ground Station
Let's create a ground station that will be in view from the final geostationary orbit. By looking at
the DefaultGroundTrackPlot window, our spacecraft is positioned over the Indian Ocean. A ground
station in India should be in view. We can choose the Hyderabad facility, which has the following
properties:
• Latitude: 17.0286 deg
• Longitude: 78.1883 deg
• Altitude: 0.541 km
Let's create this ground station in GMAT:
1.
2.
First, close all graphics and solver windows, to allow full manipulation of resources.
On the Resources tab, right-click the Ground Station folder and click Add Ground Station.
This will create a new resource called GroundStation1.
161
Tutorials
Finding Eclipses and Station Contacts
3.
4.
Rename GroundStation1 to Hyderabad.
Double-click Hyderabad to edit its configuration.
The following values are configured appropriately by default, so we won't change them:
• Min. Elevation: This is the minimum elevation angle from the ground station for a valid
contact. The current value (7 deg) is appropriate for this case.
• Central Body: Earth is the only allowed value at this time.
5. In the State Type list, select Spherical. This allows input in latitude, longitude, and altitude.
6. In the Horizon Reference list, select Ellipsoid.
7. In the Latitude box, type 17.0286.
8. In the Longitude box, type 78.1883.
9. In the Altitude box, type 0.541.
10. Click OK to accept these changes.
The configured GroundStation should look like the following screenshot:
If you add the GroundStation to the DefaultGroundTrackPlot, you can see the location visually:
162
Finding Eclipses and Station Contacts
Tutorials
Create and Configure the ContactLocator
Now we can create a ContactLocator that will search for contact times between our spacecraft and
the Hyderabad station.
1.
2.
On the Resources tab, right-click the Event Locators folder, point to Add, and click ContactLocator. This will create ContactLocator1.
Double-click ContactLocator1 to edit the configuration.
Many of the default values are identical to the EclipseLocator, so we don't need to explain
them again. There are a couple new properties that we'll note, but won't change:
3.
4.
5.
• Occulting Bodies: These are celestial bodies that GMAT will search for occultations of the
line of sight between the spacecraft and the ground station. Since our spacecraft is orbiting
the Earth, we don't need to choose any occulting bodies. Note that Earth is considered
automatically because it is the central body of the ground station.
• Light-time direction: This is the signal sense of the ground station. You can choose to
calculate light-time delay as if the ground station is transmitting, or if it is receiving.
In the Observers list, enable Hyderabad. This will cause GMAT to search for contacts to
this station.
In the Step size box, type 600. Since we're not using third-body occultations, this step size
can be increased significantly without missing events. See the ContactLocator documentation
for details.
Click OK to accept the changes.
When fully configured, the GroundStation1 window will look like the following screenshot:
163
Tutorials
Finding Eclipses and Station Contacts
Run the Mission
Now it's time to run the mission again and look at these new results.
1.
Click Run ( ) to run the mission.
The contact search will take much less time than the eclipse search, since we're using a larger
step size. As it progresses, you'll see the following message in the message window at the bottom
of the screen:
2.
3.
Finding events for ContactLocator ContactLocator1 ...
Celestial body properties are provided by SPICE kernels.
When the run is complete, click the Output tab to view the available output.
Double-click ContactLocator1 to view the report.
You'll see a report that looks similar to this:
164
Finding Eclipses and Station Contacts
Tutorials
Notice that two contact intervals were found: one about 6 minutes long at the very beginning of the
mission (it starts at the Spacecraft's initial epoch), and a second one about 29 hours long, starting
once it gets into geosynchronous orbit and extending to the end of the simulation.
•
Click Close to close the report. The report text is still available as ContactLocator1.txt
in the GMAT output folder.
Further Exercises
To expand on this tutorial, try the following exercise:
• For a mission like this, you probably will want ground station coverage during both maneuvers.
Try the following steps to make sure the coverage is adequate:
• Change the colors of the Propagate commands, so you can see visually where the burns are
located.
• Add GroundStation resources near the locations of the burns on the ground track.
• Confirm the burn epochs in the Command Summary for each Maneuver command.
• Confirm in the contact report that these times occur during a contact interval.
• Check the eclipse report, too: you may not want to perform a maneuver during an eclipse!
This tutorial shows you the basics of adding eclipse and station contact location to your mission.
These resources have a lot of power, and there are many different ways to use them. Consult the
ContactLocator and EclipseLocator documentation for details.
165
166
Tutorials
Electric Propulsion
Audience
Length
Prerequisites
Script File
Beginner
15 minutes
Complete Simulating an Orbit
Tut_ElectricPropulsionModelling.script
Objective and Overview
In this tutorial, we will use GMAT to perform a finite burn for a spacecraft using an electric propulsion system. Note that targeting and design using electric propulsion is identical to chemical propulsion and we refer you to the tutorial named Target Finite Burn to Raise Apogee for targeting configuration. This tutorial focuses only on configuration and modelling using electric propulsion systems.
The basic steps of this tutorial are:
1.
2.
Create and configure the Spacecraft hardware and FiniteBurn Resources
Configure the Mission Sequence. To do this, we will
Create Begin/End FiniteBurn commands with default settings.
Create a Propagate command to propagate while applying thrust from the electric propulsion system.
Run the mission
a.
b.
3.
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, Fuel Tank, and Solar Power System
To model thrust and fuel use associated with a finite burn, we must create an ElectricThruster,
an ElectricTank, a power system, and then attach the newly created ElectricTank to the ElectricThruster, and attach all hardware to the spacecraft. We'll start by creating the hardware objects.
1.
2.
3.
In the Resources tree, right-click on the Hardware folder, point to Add, and click ElectricThruster. A Resource named ElectricThruster1 will be created.
In the Resources tree, right-click on the Hardware folder, point to Add, and click ElectricTank. A Resource named ElectricTank1 will be created.
In the Resources tree, right-click on the Hardware folder, point to Add, and click SolarPowerSystem. A Resource named SolarPowerSystem1 will be created.
Configure the Hardware
Now we'll configure the hardware models for this exercise.
1.
Double-click ElectricThruster1 to edit its properties.
167
Tutorials
Electric Propulsion
2.
3.
4.
In the Mass Change group box, check Decrement Mass.
In the Mass Change group box, select ElectricTank1 for the Tank.
In the Thrust Config group box, select ConstantThrustAndIsp for ThrustModel and set
ConstantThrust to 5.0 N.
Figure 101 below shows the ElectricThruster1 configuration that we will use.
Figure 101. ElectricThruster1 Configuration
168
Electric Propulsion
Tutorials
We will use the default tank settings. Figure 102 shows the finished ElectricTank1 configuration.
Figure 102. ElectricTank1 Configuration
1.
2.
3.
Double-click SolarPowerSystem1 to edit its properties.
In the General group box, click the Select button next to ShadowBodies.
Remove Earth from the ShadowBodies list.
Figure 103 shows the finished SolarPowerSystem1 configuration.
Figure 103. SolarPowerSystem1 Configuration
Attach Hardware to the Spacecraft
1.
2.
3.
4.
In the Resources tree, double-click DefaultSC to edit its properties.
Select the Tanks tab. In the Available Tanks column, select ElectricTank1. Then click the
right arrow button to add ElectricTank1 to the SelectedTanks list. Click Apply.
Select the Actuators tab. In the Available Thrusters column, select ElectricThruster1. Then
click the right arrow button to add ElectricThruster1 to the SelectedThrusters list. Click OK.
Select the PowerSystem tab. In the PowerSystem tab, select SolarPowerSystem1. Click OK.
169
Tutorials
Electric Propulsion
Figure 104. Attach ElectricTank1 to DefaultSC
170
Electric Propulsion
Tutorials
Figure 105. Attach ElectricThruster1 to DefaultSC
171
Tutorials
Electric Propulsion
Figure 106. Attach SolarPowerSystem1 to DefaultSC
Create the Finite Burn Maneuver
We’ll need a single FiniteBurn Resource for this tutorial.
1.
2.
3.
In the Resources tree, right-click the Burns folder and add a FiniteBurn. A Resource named
FiniteBurn1 will be created.
Double-click FiniteBurn1 to edit its properties.
Use the menu to the right of the Thruster field to select ElectricThruster1 as the thruster
associated with FiniteBurn1. Click OK.
Figure 107. Creation of FiniteBurn Resource FiniteBurn1
172
Electric Propulsion
Tutorials
Configure the Mission Sequence
Now we will configure the mission sequence to apply a finite maneuver using electric propulsion for
a two day propagation. When we're done, the mission sequence will appear as shown below.
Figure 108. Final Mission Sequence
Create the Commands
1.
2.
3.
4.
5.
In the Mission Tree, right click on Propagate1, select Rename, and enter Propagate Two
Days.
Right click on the command named Propagate Two Days, select Insert Before, then select
BeginFiniteBurn.
Right click on the command named Propagate Two Days, select Insert After, then select
EndFiniteBurn.
Rename the command named BeginFiniteBurn1 to StartTheManeuver.
Rename the command named EndFiniteBurn1 to EndTheManeuver.
Note that for more complex analysis that has multiple FiniteBurn objects, you will need to configure
the BeginFiniteBurn and EndFiniteBurn commands to select the desired FiniteBurn Resource.
As there is only one FiniteBurn Resource in this example, the system automatically selected the
correct FiniteBurn Resource.
Configure the Propagate Command
Configure the Propagate Two Days command to propagate for DefaultSC.ElapsedDays = 2.0
Figure 109. Prop To Perigee Command Configuration
173
Tutorials
Electric Propulsion
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 the orbit spiral way from Earth. Note we exaggerated the thrust
level so that an appreciable change in the orbit occurs in two days.
Figure 110. 3D View of Finite Electric Maneuver
174
Tutorials
Simulate DSN Range and Doppler Data
Audience
Length
Prerequisites
Script Files
Intermediate level
40 minutes
Basic Mission Design Tutorials
Tut_Simulate_DSN_Range_and_Doppler_Data.script
Tut_Simulate_DSN_Range_and_Doppler_Data_3_weeks.script
Objective and Overview
Note
GMAT currently only accommodates two way measurements and thus the measurements being considered here are DSN two way range and DSN two way Doppler.
In this tutorial, we will use GMAT to generate simulated DSN range and Doppler measurement data
for a sample spacecraft in orbit about the Sun. The spacecraft in this tutorial is in an Earth “drift
away” type orbit about 1 AU away from the Sun and almost 300 million km away from the Earth.
The basic steps of this tutorial are:
1.
2.
3.
4.
5.
6.
7.
Create and configure the spacecraft, spacecraft transponder, and related parameters
Create and configure the Ground Station and related parameters
Define the types of measurements to be simulated
Create and configure Force model and propagator
Create and configure Simulator object
Run the mission and analyze the results
Create a realistic GMAT Measurement Data (GMD) file
Note that this tutorial, unlike most of the mission design tutorials, will be entirely script based. This
is because most of the resources and commands related to navigation are not implemented in the
GUI and are only available via the script interface.
As you go through the tutorial below, it is recommended that you paste the script segments into
GMAT as you go along. After each paste into GMAT, you should perform a syntax check by hitting
the Save, Sync button (
). To avoid syntax errors, where needed, don’t forget to add the
following command to the last line of the script segment you are checking.
BeginMissionSequence
We note that in addition to the material presented here, you should also look at the individual
Help resources for all the objects and commands we create and use here. For example, Spacecraft,
Transponder, Transmitter, GroundStation, ErrorModel, TrackingFileSet, RunSimulator, etc
all have their own Help pages.
175
Tutorials
Simulate DSN Range and Doppler
Data
Create and configure the spacecraft, spacecraft transponder, and related parameters
For this tutorial, you’ll need GMAT open, with a new empty script open. To create a new script,
click New Script, ( )
Create a satellite and set its epoch and Cartesian coordinates
Since this is a Sun-orbiting spacecraft, we choose to represent the orbit in a Sun-centered coordinate
frame which we define using the scripting below.
% Create the Sun-centered J2000 frame.
Create CoordinateSystem SunMJ2000Eq;
SunMJ2000Eq.Origin = Sun;
SunMJ2000Eq.Axes
= MJ2000Eq; %Earth mean equator axes
Next, we create a new spacecraft, Sat, and set its epoch and Cartesian coordinates.
Create Spacecraft Sat;
Sat.DateFormat
=
Sat.CoordinateSystem =
Sat.DisplayStateType =
Sat.Epoch
=
Sat.X
=
Sat.Y
=
Sat.Z
=
Sat.VX
=
Sat.VY
=
Sat.VZ
=
Sat.Id
UTCGregorian;
SunMJ2000Eq;
Cartesian;
19 Aug 2015 00:00:00.000;
-126544968
61978514
24133221
-13.789
-24.673
-10.662
= 11111;
Note that, in addition to setting Sat’s coordinates, we also assigned it an ID number. This is the
number that will be written to the GMAT Measurement Data (GMD) file that we will discuss later.
Create a Transponder object and attach it to our spacecraft
To simulate navigation measurements for a given spacecraft, GMAT requires that a Transponder
object, which receives the ground station uplink signal and re-transmits it, typically, to a ground
station, be attached to the spacecraft. Below, we create the Transponder object and attach it to our
spacecraft.
Create Antenna HGA;
Create Transponder SatTransponder;
SatTransponder.PrimaryAntenna
= HGA;
SatTransponder.HardwareDelay
= 1e-06; %seconds
SatTransponder.TurnAroundRatio
= '880/749';
Sat.AddHardware
176
= {SatTransponder, HGA};
Simulate DSN Range and Doppler
Data
Tutorials
After we create the Transponder object, there are three fields, PrimaryAntenna, HardwareDelay,
and TurnAroundRatio that must be set.
The PrimaryAntenna is the antenna that the spacecraft transponder, SatTransponder, uses to
receive and retransmit RF signals. In the example above, we set this field to HGA which is an
Antenna object we have created. Currently the Antenna resource has no function but in a future
release, it may have a function. HardwareDelay, the transponder signal delay in seconds, is set to one
micro-second. We set TurnAroundRatio, which is the ratio of the retransmitted to the input signal,
to '880/749.' See the FRC-21_RunSimulator Help and Appendix A – Determination of Measurement
Noise Values for a discussion on how GMAT uses this input field. As described in the Help, if our
DSN data does not use a ramp table, this turn around ratio is used directly to calculate the Doppler
measurements.
Note that in the last script command above, we attach our newly created Transponder and its related
Antenna object to our spacecraft, Sat.
Create and configure the Ground Station and related parameters
Create Ground Station Transmitter, Receiver, and Antenna objects
Before we create the GroundStation object itself, as shown below, we first create the Transmitter,
Receiver, and Antenna objects that must be associated with any GroundStation.
% Ground Station electronics.
Create Transmitter DSNTransmitter;
Create Receiver DSNReceiver;
Create Antenna DSNAntenna;
DSNTransmitter.PrimaryAntenna
DSNReceiver.PrimaryAntenna
DSNTransmitter.Frequency
= DSNAntenna;
= DSNAntenna;
= 7200;
%MHz
In the script segment above, we first created Transmitter, Receiver, and Antenna objects. The
GMAT script line DSNTransmitter.PrimaryAntenna = DSNAntenna, sets the main antenna
that the Transmitter object will be using. Likewise, the DSNReceiver.PrimaryAntenna =
DSNAntenna script line sets the main antenna that the Receiver object will be using. As previously
mentioned, the Antenna object currently has no function, but we include it here both because
GMAT requires it and for completeness since the Antenna resource may have a function in a future
GMAT release. Finally, we set the transmitter frequency in the last GMAT script line above. See the
RunSimulator Help for a complete description of how this input frequency is used. As described
in the Help, since in this example we will not be using a ramp table, this input frequency will be
used to calculate the simulated value of the range and Doppler observations. In addition, this input
frequency will also be output to the range data file created by the RunSimulator command.
Create Ground Station
Below, we create and configure a GroundStation object.
%
Create ground station and associated error models
177
Tutorials
Simulate DSN Range and Doppler
Data
Create GroundStation CAN;
CAN.CentralBody
= Earth;
CAN.StateType
= Cartesian;
CAN.HorizonReference
= Ellipsoid;
CAN.Location1
= -4461.083514
CAN.Location2
= 2682.281745
CAN.Location3
= -3674.570392
CAN.Id
= 22222;
CAN.MinimumElevationAngle = 7.0;
CAN.IonosphereModel
CAN.TroposphereModel
= 'IRI2007';
= 'HopfieldSaastamoinen';
CAN.AddHardware
= {DSNTransmitter, DSNAntenna, ...
DSNReceiver};
The script segment above is broken into five sections. In the first section, we create our GroundStation object and we set our Earth-Centered Fixed Cartesian coordinates. In the second section, we
set the ID of the ground station that will output to the GMD file created by the RunSimulator
command. In the third section, we set the minimum elevation angle to 7 degrees. Below this ground
station to spacecraft elevation angle, no simulated data will be created. In the fourth section, we
specify which troposphere and ionosphere model we wish to use to model RF signal atmospheric
refraction effects. Finally, in the fifth section, we attached three pieces of previously created required
hardware to our ground station, a transmitter, a receiver, and an antenna.
Create Ground Station Error Models
It is well known that all measurement types have random noise and/or biases associated with them.
For GMAT, these affects are modelled using ground station error models. Since we have already
created the GroundStation object and its related hardware, we now create the ground station error
models. Since we wish to simulate both range and Doppler data, we need to create two error models
as shown below, one for range measurements and one for Doppler measurements.
%
Create Ground station error models
Create ErrorModel DSNrange;
DSNrange.Type
= 'Range_RU';
DSNrange.NoiseSigma
= 10.63;
DSNrange.Bias
= 0.0;
Create ErrorModel DSNdoppler;
DSNdoppler.Type
DSNdoppler.NoiseSigma
DSNdoppler.Bias
= 'Doppler_HZ';
= 0.0282;
= 0.0;
CAN.ErrorModels
= {DSNrange, DSNdoppler};
The script segment above is broken into three sections. The first section defines an ErrorModel
named DSNrange. The error model Type is Range_RU which indicates that it is an error model
178
Simulate DSN Range and Doppler
Data
Tutorials
for DSN range measurements. The 1 sigma standard deviation of the Gaussian white noise is set to
10.63 Range Units (RU) and the measurement bias is set to 0 RU.
The second section above defines an ErrorModel named DSNdoppler. The error model Type is
Doppler_HZ which indicates that it is an error model for DSN Doppler measurements. The 1 sigma
standard deviation of the Gaussian white noise is set to 0.0282 Hz and the measurement bias is set
to 0 Hz.
The third section above attaches the two ErrorModel resources we have just created to the CAN
GroundStation. Note that in GMAT, the measurement noise or bias is defined on a per ground
station basis. Thus, any range measurement error involving the CAN GroundStation is defined by
the DSNRange ErrorModel and any Doppler measurement error involving the CAN GroundStation is defined by the DSNdoppler ErrorModel. Note that since GMAT currently only models
two way measurements where the transmitting and receiving ground stations are the same, we do
not have to consider the case where the transmitting and receiving ground stations are different.
Suppose we were to add an additional GroundStation to this simulation. The measurement error
for observations involving this new GroundStation would be defined by the ErrorModel resources
attached to it.
See Appendix A – Determination of Measurement Noise Values for a discussion of how we determined the values for NoiseSigma for the two ErrorModel resources we created.
Define the types of measurements to be simulated
Now we will create and configure a TrackingFileSet resource. This resource defines the type of
data to be simulated, the ground stations that will be used, and the file name of the output GMD file
which will contain the simulated data. In addition, the TrackingFileSet resource will define needed
simulation parameters for the various data types.
Create TrackingFileSet DSNsimData;
DSNsimData.AddTrackingConfig
= {{CAN, Sat, CAN}, 'DSNRange'};
DSNsimData.AddTrackingConfig
= {{CAN, Sat, CAN}, 'Doppler'};
DSNsimData.FileName
= ...
{'Sat_dsn_range_and_doppler_measurements.gmd'};
DSNsimData.UseLightTi
DSNsimData.UseRelativityCorrection
DSNsimData.UseETminusTAI
= true;
= true;
= true;
DSNsimData.SimDopplerCountInterval
DSNsimData.SimRangeModuloConstant
= 10.0;
= 3.3554432e+07;
The script lines above are broken into three sections. In the first section, the resource name, DSNsimData, is declared, the data types are defined, and the output file name is specified. AddTrackingConfig is the field that is used to define the data types. The first AddTrackingConfig line tells
GMAT to simulate DSN range two way measurements for the CAN to Sat to CAN measurement
strand. The second AddTrackingConfig line tells GMAT to simulate DSN Doppler two way measurements for the CAN to Sat to CAN measurement strand.
The second section above sets some simulation parameters that apply to both the range and Doppler
measurements. We set UseLightTime to True in order to generate realistic measurements where
179
Tutorials
Simulate DSN Range and Doppler
Data
GMAT takes into account the finite speed of light. The last two parameters in this section, UseRelativityCorrection and UseETminusTAI, are set to True so that general relativistic corrections, as
described in Moyer [2000], are applied to the light time equations.
The third section above sets simulation parameters that apply to a specific measurement type. SimDopplerCountInterval applies only to Doppler measurements and SimRangeModuloConstant
applies only to range measurements. We note that the “Sim” in the field names is used to indicate that
these fields only are applicable when GMAT is in simulation mode (i.e., when using the RunSimulator command) data and not when GMAT is in estimation mode (i.e., when using the RunEstimator command). SimDopplerCountInterval, the Doppler Count Interval, is set to 10 seconds
and SimRangeModuloConstant, the maximum possible range value, is set to 33554432. See the
RunSimulator Help and Appendix A – Determination of Measurement Noise Values for a description of
how these parameters are used to calculate the measurement values.
Create and configure Force model and propagator
We now create and configure the force model and propagator that will be used for the simulation.
For this deep space drift away orbit, we naturally choose the Sun as our central body. Since we are
far away from all the planets, we use point mass gravity models and we include the effects of the
Sun, Earth, Moon, and most of the other planets. In addition, we model Solar Radiation Pressure
(SRP) affects and we include the affect of general relativity on the dynamics. The script segment
accomplishing this is shown below.
Create ForceModel Fm;
Create Propagator Prop;
Fm.CentralBody
Fm.PointMasses
= Sun;
= {Sun, Earth, Luna, Mars, Saturn, ...
Uranus, Mercury, Venus, Jupiter};
Fm.SRP
= On;
Fm.RelativisticCorrection = On;
Prop.FM
= Fm;
Create and configure Simulator object
As shown below, we create and configure the Simulator object used to define our simulation.
Create Simulator Sim;
Sim.AddData
Sim.EpochFormat
Sim.InitialEpoch
Sim.FinalEpoch
Sim.MeasurementTimeStep
Sim.Propagator
Sim.AddNoise
=
=
=
=
=
=
=
{DSNsimData};
UTCGregorian;
'19 Aug 2015 00:00:00.000';
'19 Aug 2015 00:12:00.000';
600;
Prop;
Off;
In the first script line above, we create a Simulator object, Sim. The next field set is AddData
which is used to specify which TrackingFileSet should be used. Recall that the TrackingFileSet
specifies the type of data to be simulated and the file name specifying where to store the data. The
TrackingFileSet, DSNsimData, that we created in the Define the types of measurements to be
180
Simulate DSN Range and Doppler
Data
Tutorials
simulated section, specified that we wanted to simulate two way DSN range and Doppler data that
involved the CAN GroundStation.
The next three script lines, which set the EpochFormat, InitialEpoch, and FinalEpoch fields,
specify the time period of the simulation. Here, we choose a short 12 minute duration.
The next script line sets the MeasurementTimeStep field which specifies the requested time between measurements. We choose a value of 10 minutes. This means that our data file will contain a
maximum of two range measurements and two Doppler measurements.
The next script line sets the Propagator field which specifies which Propagator object should be
used. We set this field to the Prop Propagator object which we created in the Create and configure
Force model and propagator section.
Finally, in the last line of the script segment, we set the AddNoise field which specifies whether or
not we want to add noise to our simulated measurements. The noise that can be added is defined
by the ErrorModel objects that we created in the Create and configure the Ground Station and
related parameters section. As discussed in the Create and configure the Ground Station and related
parameters section and Appendix A – Determination of Measurement Noise Values, the noise added to
the range measurements would be Gaussian with a one sigma value of 10.63 Range Units and the
noise added to the Doppler measurements would be Gaussian with a one sigma value of 0.0282 Hz.
For this simulation, we choose not to add noise.
Run the mission and analyze the results
The script segment used to run the mission is shown below.
BeginMissionSequence
RunSimulator Sim
The first script line, BeginMissionSequence, is a required command which indicates that the
“Command” section of the GMAT script has begun. The second line of the script issues the
RunSimulator command with the Sim Simulator resource, defined in the Create and configure
Simulator object section, as an argument. This tells GMAT to perform the simulation specified by
the Sim resource.
We have now completed all of our script segments. See the file, Simulate DSN Range and
Doppler Data.script, for a listing of the entire script. We are now ready to run the script. Hit
the Save,Sync,Run button, (
). Because we are only simulating a small amount of data, the
script should finish execution in about one second.
Let’s
take
a
look
at
the
output
created.
The
file
created,
Sat_dsn_range_and_doppler_measurements.gmd, was specified in the TrackingFileSet
resource, DSNsimData, that we created in the Define the types of measurements to be simulated
section. The default directory, if none is specified, is the GMAT ‘output’ directory. Let’s analyze the
contents of this “GMAT Measurement Data” or GMD file as shown below.
% GMAT Internal Measurement Data File
27253.500405092593 DSNRange 9004 22222 11111 26016945.24902344 2 7.2e+009 3.3554432e+007
27253.500405092593 Doppler 9006 22222 11111 2 10 -8459336323.89349840
181
Tutorials
Simulate DSN Range and Doppler
Data
27253.507349537038 DSNRange 9004 22222 11111 21728172.10375977 2 7.2e+009 3.3554432e+007
27253.507349537038 Doppler 9006 22222 11111 2 10 -8459335611.28409770
The first line of the file is a comment line indicating that this is a file containing measurement data
stored in GMAT’s internal format. There are 4 lines of data representing range data at two successive
times and Doppler data at two successive times. As we expected, we have no more than 4 total
measurements. Refer to the TrackingFileSet Help for a description of the range and Doppler GMD
file format.
We now analyze the first line of data which represents a DSN two way range measurement at the
start of the simulation at '19 Aug 2015 00:00:00.000 UTCG’ which corresponds to the output TAI
modified Julian Day of 27253.500405092593 TAIMJD.
The second and third fields, DSNRange and 9004, are just internal GMAT codes indicating the use
of DSN range (Trk 2-34 type 7) data.
The 4th field, 22222, is the Downlink station ID. This is the ID we gave the CAN GroundStation
object that we created in the Create and configure the Ground Station and related parameters section.
The 5th field, 11111, is the spacecraft ID. This is the ID we gave the Sat Spacecraft object that we
created in the Create and configure the spacecraft, spacecraft transponder, and related parameters
section.
The 6th field, 26016945.24902344, is the actual DSN range observation value in RU.
The 7th field, 2, is an integer which represents the Uplink Band of the uplink GroundStation, CAN.
The designation, 2, represents X-band. See the RunSimulator Help for a detailed discussion of how
GMAT determines what value should be written here. As described in the Help, since we are not
using a ramp table, GMAT determines the Uplink Band by looking at the transmit frequency of
the Transmitter object attached to the CAN ground station. GMAT knows that the 7200 MHz
value that we assigned to CAN’s Transmitter resource, DSNTransmitter, corresponds to an Xband frequency.
The 8th field, 7.2e+009, is the transmit frequency of CAN at the time of the measurement. Since
we are not using a ramp table, this value will be constant for all measurements and it is given by the
value of the frequency of the Transmitter object, DSNTransmitter, that we attached to the CAN
ground station. Recall the following script segment, DSNTransmitter.Frequency = 7200;
%MHz, from the Create and configure the Ground Station and related parameters section.
The 9th field, 3.3554432e+007, represents the integer range modulo number that helps define the
DSN range measurement. This is the value that we set when we created and configured the TrackingFileSet DSNsimData object in the Define the types of measurements to be simulated section.
Recall the following script command,
DSNsimData.SimRangeModuloConstant = 3.3554432e+07;
This range modulo number is discussed in Appendix A – Determination of Measurement Noise Values and
is defined as M, the length of the ranging code in RU.
We now analyze the second line of data which represents a DSN two way Doppler measurement at
the start of the simulation at '19 Aug 2015 00:00:00.000 UTCG’ which corresponds to the output
TAI modified Julian Day of 27253.500405092593 TAIMJD.
182
Simulate DSN Range and Doppler
Data
Tutorials
The second and third fields, Doppler and 9006, are just internal GMAT codes indicating the use of
DSN Doppler (derived from two successive Trk 2-34 type 17 Total Count Phase measurements) data.
The 4th field, 22222, is the Downlink station ID. This is the ID we gave the CAN GroundStation
object that we created in the Create and configure the Ground Station and related parameters section.
The 5th field, 11111, is the spacecraft ID. This is the ID we gave the Sat Spacecraft object that we
created in the Create and configure the spacecraft, spacecraft transponder, and related parameters
section.
The 6th field, 2, is an integer which represents the Uplink Band of the uplink GroundStation, CAN.
As we mentioned when discussing the range measurement, the designation, 2, represents X-band.
The 7th field, 10, is the Doppler Count Interval (DCI) used to help define the Doppler measurement.
This is the value that we set when we created and configured the TrackingFileSet DSNsimData
object in the Define the types of measurements to be simulated section. Recall the following script
command,
DSNsimData.SimDopplerCountInterval = 10.0;
The DCI is also discussed in Appendix A – Determination of Measurement Noise Values.
The 8th field, -7819057474.22393610, is the actual DSN Doppler observation value in Hz.
The third line of data represents the second DSN two way range measurement at '19 Aug
2015 00:10:00.000 UTCG’ which corresponds to the output TAI modified Julian Day time of
27253.507349537038 TAIMJD. The fourth line of data represents the second DSN two way Doppler
measurement at '19 Aug 2015 00:10:00.000 UTCG.’
Create a more realistic GMAT Measurement Data (GMD)
We have run a short simple simulation and generated a sample GMD file. Our next goal is to generate
a realistic GMD file that a different script can read in and generate an orbit determination solution.
To add more realism, we will do the following:
• Generate data from additional ground stations
• Add the use of a ramp table
• Perform a longer simulation
• Add measurement noise
In order to generate measurement data from additional ground stations, we must first create and
configure additional GroundStation objects. Below, we create and configure two new ground stations, GDS and MAD.
Create GroundStation GDS;
GDS.CentralBody
= Earth;
GDS.StateType
= Cartesian;
GDS.HorizonReference
= Ellipsoid;
GDS.Location1
= -2353.621251;
GDS.Location2
= -4641.341542;
183
Tutorials
Simulate DSN Range and Doppler
Data
GDS.Location3
GDS.Id
GDS.AddHardware
GDS.MinimumElevationAngle
GDS.IonosphereModel
GDS.TroposphereModel
=
=
=
=
=
=
3677.052370;
'33333';
{DSNTransmitter, DSNAntenna, DSNReceiver};
7.0;
'IRI2007';
'HopfieldSaastamoinen';
Create GroundStation MAD;
MAD.CentralBody
MAD.StateType
MAD.HorizonReference
MAD.Location1
MAD.Location2
MAD.Location3
MAD.Id
MAD.AddHardware
MAD.MinimumElevationAngle
MAD.IonosphereModel
MAD.TroposphereModel
=
=
=
=
=
=
=
=
=
=
=
Earth;
Cartesian;
Ellipsoid;
4849.519988;
-0360.641653;
4114.504590;
'44444';
{DSNTransmitter, DSNAntenna, DSNReceiver};
7.0;
'IRI2007';
'HopfieldSaastamoinen';
Now that we have defined two additional ground stations, we must specify the measurement noise
associated with these new ground stations. This can be done using the previously created ErrorModel resources as shown below.
GDS.ErrorModels
MAD.ErrorModels
= {DSNrange, DSNdoppler};
= {DSNrange, DSNdoppler};
Next, we must add the corresponding two way range and Doppler measurements associated with
our new ground stations to our TrackingFileSet object, DSNsimData, as shown below.
DSNsimData.AddTrackingConfig = {{GDS, Sat, GDS}, 'DSNRange'};
DSNsimData.AddTrackingConfig = {{GDS, Sat, GDS}, 'Doppler'};
DSNsimData.AddTrackingConfig = {{MAD, Sat, MAD}, 'DSNRange'};
DSNsimData.AddTrackingConfig = {{MAD, Sat, MAD}, 'Doppler'};
We now create our ramp table that many but not all missions use. A ramp table is a table that allows
GMAT to calculate the transmit frequency of all the ground stations involved in our simulation.
Recall that GMAT needs to know the transmit frequency, as a function of time, in order to calculate
the value of the observations. The term “ramp” is used because the transmit frequency increases
linearly with time and a graph of transmit frequency vs. time would typically show a ramp. A mission
that does not use a ramp table simply uses a constant transmit frequency for a given ground station.
To modify our script to accommodate the use of a ramp table, we modify our TrackingFileSet
object, DSNsimData, as shown below.
DSNsimData.RampTable = ...
{'../output/Simulate DSN Range and Doppler Data 3 weeks.rmp'};
We must now create a file with the name shown above in the GMAT ‘output’ directory. Refer to
the TrackingFileSet Help for a description of the ramp table file format. In order for GMAT to
184
Simulate DSN Range and Doppler
Data
Tutorials
determine the transmit frequencies of all the ground stations, the ramp table must have at least one
row of data for every ground station providing measurement data. The contents of our ramp table
is shown below.
27252 22222 11111 2 1 7.2e09 0.2
27252 33333 11111 2 1 7.3e09 0.3
27252 44444 11111 2 1 7.4e09 0.4
Each row of data above is called a ramp record. Let’s analyze the first ramp record. The first field,
27252, is the TAIMJD date of the ramp record.
The second field, 22222, is the ground station ID of the GroundStation object whose frequency
is being specified. We note that the ID 22222 corresponds to the CAN ground station. The third
field, 11111, is the ID of the spacecraft that the CAN ground station is transmitting to. We recognize
11111 as the ID of the Sat spacecraft.
The 4th field, 2, is an integer representing the uplink band of the transmission. The integer 2 represents X-band. The 5th field, 1, is an integer describing the ramp type. The integer 1 represents
the start of a new ramp.
The 6th field, 7.2e9, is the transmission frequency in Hz, from CAN to Sat at the time given by the
first field. The 7th input is the ramp rate in Hz/s.
We now describe how GMAT uses the ramp record to determine the transmit frequency of CAN
to Sat at a given time. We let TAIMJD be the time associated with the ramp record. Then GMAT
will calculate the value of the transmit frequency at t = 27252.5 TAIMJD as shown below.
where
Note that, in the typical case where there are numerous ramp records, it is assumed that
is
chosen as close to time t as possible. For our case above, the transmit frequency from CAN to Sat
at time t is
The second and third rows of the ramp table allow GMAT to calculate the transmit frequency from
GDS to Sat and MAD to Sat, respectively. We now create a file, Simulate DSN Range and
Doppler Data Realistic GMD.rmp, with the contents shown above and place it in GMAT’s
‘output’ folder.
We make one final comment about the use of a ramp table. We note that when a ramp table is used, GMAT uses the various script inputs (e.g., SatTransponder.TurnAroundRatio and
DSNTransmitter.Frequency) differently. See the RunSimulator Help for details.
We only have two steps remaining in order to create a script that generates more realistic measurement data. The first step is to increase the simulation time from 10 minutes to the more realistic
3 weeks worth of data that is typically needed to generate an orbit determination solution for a
spacecraft in this type of deep space orbit. The second step is to turn on the measurement noise.
185
Tutorials
Simulate DSN Range and Doppler
Data
These two steps are accomplished by making the following changes to our TrackingFileSet object,
DSNsimData.
Sim.FinalEpoch
= '09 Sep 2015 00:00:00.000';
Sim.AddNoise
= On;
Sim.MeasurementTimeStep = 3600;
Note that above, in addition to implementing the two needed steps, we also changed the measurement time step from 600 seconds to 3600 seconds. This is not a realistic time step as many missions
would use a time step that might even be less than 600 seconds. We used this larger time step for
tutorial purposes only so that the script would not take too long to run.
A complete script, containing all the changes we have made in the Create a
more realistic GMAT Measurement Data (GMD) section, is contained in the file,
Tut_Simulate_DSN_Range_and_Doppler_Data_3_weeks.script. Note that in this file,
in addition to the changes above, we have also changed the GMD output file name to Simulate
DSN Range and Doppler Data 3 weeks.gmd.
Now run the script which should take approximately 1-2 minutes since we are generating much more
data than previously. We will use the GMD file we have created here as input to an estimation script
we will build in the next tutorial, Orbit Estimation using DSN Range and Doppler Data.
References
Mesarch [2007] M. Mesarch, M. Robertson, N. Ottenstein, A. Nicholson, M. Nicholson, D. Ward,
J. Cosgrove, D. German, S. Hendry, J. Shaw, “Orbit Determination and Navigation
of the SOlar TErrestrial Relations Observatory (STEREO)”, 20th International
Symposium on Space Flight Dynamics, Annapolis, MD, September 24-28, 2007.
Moyer [2000]
Moyer, Theodore D., Formulation for Observed and Computed Values of Deep
Space Network Data Types for Navigation (JPL Publication 00-7), Jet Propulsion
Laboratory, California Institute of Technology, October 2000.
Schanzle [1995] Schanzle, A., Orbit Determination Error Analysis System (ODEAS) Report on
Error Sources and Nominal 3-Sigma Uncertainties for Covariance Analysis Studies Using ODEAS (Update No. 2), Computer Sciences Corporation (CSC) memo
delivered as part of NASA contract NAS-5-31500, May 31, 1995.
Appendix A – Determination of Measurement Noise Values
We now say a few words on how we determined the values for NoiseSigma for the two ErrorModel resources we created. The computed value of the DSN range measurement is given by (Moyer
[2000]):
where
186
Simulate DSN Range and Doppler
Data
Tutorials
We note that M as defined above is equal to SimRangeModuloConstant which was discussed in
the Define the types of measurements to be simulated section.
By manipulation of the equation above, we can find a relationship between RU and meters, as shown
below.
where
If we assume the round trip distance is 1 meter, we have
Recall that in the Create and configure the Ground Station and related parameters section, we
set DSNTransmitter.Frequency = 7200; This corresponds to an X-band frequency (so,
C=221/1498) of 7200e6 Hz. For the case where a ramp table is not used, we have a constant frequency,
, and thus
For this example, for DSN range measurements, we want to use a 1 sigma noise bias of 3 meters
(Schanzle [1995]). From the calculations above, we determine that this corresponds to 3*3.543172
10.63 RU.
We now turn our attention to the DSN Doppler measurement. The DSN Doppler measurement
that GMAT uses is actually a derived observation, O, calculated using two successive Total Count
Phase, , (type 17 Trk 2-34 record) measurements as shown below.
where
In the absence of measurement noise, one can show (Moyer [2000]), that the Observed value (O)
above equals the Computed (C) value below.
where
187
Tutorials
Simulate DSN Range and Doppler
Data
Neglecting ionospheric media corrections, further calculation (Mesarch [2007]) shows that the values
of O and C can be related to an average range rate value, , as shown below.
where
Thus, we determine that
The quantity,
, above represents the measurement noise and thus the equation gives us a way
to convert measurement noise in Hz to measurement noise in mm/s. To convert from mm/s to Hz,
simply multiply by
. In our case, where we use a constant X-band frequency
of 7.2e9, the conversion factor is given by
. For this tutorial, we use a 1
sigma noise value of 1 mm/s (Schanzle [1995]) which corresponds to this value of 0.0282 Hz.
188
Tutorials
Orbit Estimation using DSN Range and
Doppler Data
Audience
Length
Prerequisites
Script Files
Intermediate level
60 minutes
Simulate DSN Range and Doppler Data Tutorial
Tut_Orbit_Estimation_using_DSN_Range_and_Doppler_Data.script
Objective and Overview
Note
GMAT currently only accommodates two way measurements and thus the measurements being considered here are DSN two way range and DSN two way Doppler.
In this tutorial, we will use GMAT to read in simulated DSN range and Doppler measurement data
for a sample spacecraft in orbit about the Sun and determine its orbit. The spacecraft is in an Earth
“drift away” type orbit about 1 AU away from the Sun and almost 300 million km away from the
Earth. This tutorial has many similarities with the Simulate DSN Range and Doppler Data Tutorial
in that most of the same GMAT resources need to be created and configured. There are differences,
however, in how GMAT uses the resources that we will point out as we go along.
The basic steps of this tutorial are:
1.
2.
3.
4.
5.
6.
Create and configure the spacecraft, spacecraft transponder, and related parameters
Create and configure the Ground Station and related parameters
Define the types of measurements to be processed
Create and configure Force model and propagator
Create and configure Batch Estimator object
Run the mission and analyze the results
Note that this tutorial, unlike most of the mission design tutorials, will be entirely script based. This
is because most of the resources and commands related to navigation are not implemented in the
GUI and are only available via the script interface.
As you go through the tutorial below, it is recommended that you paste the script segments into
GMAT as you go along. After each paste into GMAT, you should perform a syntax check by hitting
the Save, Sync button (
). To avoid syntax errors, where needed, don’t forget to add the
following command, as needed, to the last line of the script segment you are checking.
BeginMissionSequence
We note that in addition to the material presented here, you should also look at the individual
Help resources for all the objects and commands we create and use here. For example, Spacecraft,
Transponder, Transmitter, GroundStation, ErrorModel, TrackingFileSet, RunEstimator, etc
all have their own Help pages.
189
Tutorials
Orbit Estimation using DSN Range
and Doppler Data
Create and configure the spacecraft, spacecraft transponder, and related parameters
For this tutorial, you’ll need GMAT open, with a new empty script open. To create a new script,
click New Script, ( )
Create a satellite and set its epoch and Cartesian coordinates
Since this is a Sun-orbiting spacecraft, we choose to represent the orbit in a Sun-centered coordinate
frame which we define using the scripting below.
% Create the Sun-centered J2000 frame.
Create CoordinateSystem SunMJ2000Eq;
SunMJ2000Eq.Origin = Sun;
SunMJ2000Eq.Axes
= MJ2000Eq; %Earth mean equator axes
Next, we create a new spacecraft, Sat, and set its epoch and Cartesian coordinates.
Create Spacecraft Sat;
Sat.DateFormat
=
Sat.CoordinateSystem =
Sat.DisplayStateType =
Sat.Epoch
=
Sat.X
=
Sat.Y
=
Sat.Z
=
Sat.VX
=
Sat.VY
=
Sat.VZ
=
Sat.Id
UTCGregorian;
SunMJ2000Eq;
Cartesian;
19 Aug 2015 00:00:00.000;
-126544963
%-126544968
61978518
%61978514
24133225
%24133221
-13.789
-24.673
-10.662
= 11111;
Note that, in addition to setting Sat’s coordinates, we also assigned it an ID number. When GMAT
finds this number in the GMD file that it reads in, it will know that the associated data corresponds
to the Sat Spacecraft.
For the simulation tutorial, the Cartesian state above represented the “true” state. Here, the Cartesian
state represents the spacecraft operator’s best “estimate” of the state, the so-called a priori estimate.
Because, one never has exact knowledge of the true state, we have perturbed the Cartesian state above
by a few km in each component as compared to the simulated true state shown in the comment field.
Create a Transponder object and attach it to our spacecraft
To estimate an orbit state for a given spacecraft, GMAT requires that a Transponder object, which
receives the ground station uplink signal and re-transmits it, typically, to a ground station, be attached
to the spacecraft. Below, we create the Transponder object and attach it to our spacecraft. Note that
after we create the Transponder object, there are three fields, PrimaryAntenna, HardwareDelay,
and TurnAroundRatio that must be set.
Create Antenna HGA;
190
%High Gain Antenna
Orbit Estimation using DSN Range
and Doppler Data
Tutorials
Create Transponder SatTransponder;
SatTransponder.PrimaryAntenna
= HGA;
SatTransponder.HardwareDelay
= 1e-06; %seconds
SatTransponder.TurnAroundRatio = '880/749';
Sat.AddHardware
Sat.SolveFors
= {SatTransponder, HGA};
= {CartesianState};
The PrimaryAntenna is the antenna that the spacecraft transponder, SatTransponder, uses to
receive and retransmit RF signals. In the example above, we set this field to HGA which is an
Antenna object we have created. Currently the Antenna resource has no function but in a future
release, it may have a function. HardwareDelay, the transponder signal delay in seconds, is set to
one micro-second.
We set TurnAroundRatio, which is the ratio of the retransmitted to the input signal, to '880/749.'
See the RunEstimator Help for a discussion on how GMAT uses this input field. Recall that, as part
of their calculations, estimators need to form a quantity called the observation residual, O-C, where
O is the “Observed” value of a measurement and C is the “Computed,” based upon the current
knowledge of the orbit state, value of a measurement. As described in the Help, since our DSN data,
for this tutorial, uses a ramp table, this input turn around ratio is not used to calculate the computed,
C, Doppler measurements. Instead, the turn-around ratio used to calculate the computed Doppler
measurement will be inferred from the value of the uplink band contained in the ramp table.
Note that in the second to last script command above, we attach our newly created Transponder
resource, SatTransponder, and its related Antenna resource, HGA, to our spacecraft, Sat.
The last script line, which was not present in the simulation script, is needed to tell GMAT what
quantities the estimator will be estimating, the so-called “solve-fors.” Here, we tell GMAT to solve
for the 6 components of our satellite’s Cartesian state. Since we input the Sat state in SunMJ2000
coordinates, this is the coordinate system GMAT will use to solve for the Cartesian state.
Create and configure the Ground Station and related parameters
Create Ground Station Transmitter, Receiver, and Antenna objects
Before we create the GroundStation object itself, as shown below, we first create the Transmitter,
Receiver, and Antenna objects that must be associated with any GroundStation.
% Ground Station electronics.
Create Transmitter DSNTransmitter;
Create Receiver DSNReceiver;
Create Antenna DSNAntenna;
DSNTransmitter.PrimaryAntenna
DSNReceiver.PrimaryAntenna
DSNTransmitter.Frequency
= DSNAntenna;
= DSNAntenna;
= 7200;
%MHz
In the script segment above, we first created Transmitter, Receiver, and Antenna objects.
The GMAT script line DSNTransmitter.PrimaryAntenna = DSNAntenna, sets the
main antenna that the Transmitter resource, DSNTransmitter, will be using. Likewise, the
DSNReceiver.PrimaryAntenna = DSNAntenna script line sets the main antenna that the
191
Tutorials
Orbit Estimation using DSN Range
and Doppler Data
Receiver resource, DSNReceiver, will be using. As previously mentioned, the Antenna object currently has no function, but we include it here both because GMAT requires it and for completeness
since the Antenna resource may have a function in a future GMAT release. Finally, we set the transmitter frequency in the last GMAT script line above. See the RunEstimator Help for a complete
description of how this input frequency is used. As described in the Help, since in this example we
will be using a ramp table, this input frequency will not be used to calculate the computed value of
the range and Doppler observations. Instead, the frequency value in the ramp table will be used to
calculate the computed range and Doppler observations.
There is one clarification to the statement above. As discussed in the RunEstimator Help,
the DSNTransmitter.Frequency value discussed above as well as the previously discussed SatTransponder TurnAroundRatio value will be used to calculate the, typically small, media corrections needed to determine the computed, C, value of the range and Doppler measurements.
Create Ground Station
Below, we create and configure our CAN GroundStation object.
%
Create ground station
Create GroundStation CAN;
CAN.CentralBody
CAN.StateType
CAN.HorizonReference
CAN.Location1
CAN.Location2
CAN.Location3
and associated error models
CAN.Id
= 22222;
=
=
=
=
=
=
Earth;
Cartesian;
Ellipsoid;
-4461.083514
2682.281745
-3674.570392
CAN.MinimumElevationAngle = 7.0;
CAN.IonosphereModel
CAN.TroposphereModel
= 'IRI2007';
= 'HopfieldSaastamoinen';
CAN.AddHardware
= {DSNTransmitter, DSNAntenna, ...
DSNReceiver};
The script segment above is broken into five sections. In the first section, we create our GroundStation object and we set our Earth-Centered Fixed Cartesian coordinates. In the second section,
we set the ID of the ground station so that GMAT will be able to identify data from this ground
station contained in the GMD file.
In the third section, we set the minimum elevation angle to 7 degrees. Below this ground station
to spacecraft elevation angle, no measurement data will be used to form an orbit estimate. In the
fourth section, we specify which troposphere and ionosphere model we wish to use to model RF
signal atmospheric refraction effects. Finally, in the fifth section, we attach three pieces of previously
created required hardware to our ground station, a transmitter, a receiver, and an antenna.
Next, we create and configure the GDS GroundStation resource, and associated Transmitter resource.
192
Orbit Estimation using DSN Range
and Doppler Data
Tutorials
%
Create GDS transmitter and ground station
Create Transmitter GDSTransmitter
GDSTransmitter.Frequency
= 7300;
%MHz.
GDSTransmitter.PrimaryAntenna = DSNAntenna;
Create GroundStation GDS;
GDS.CentralBody
GDS.StateType
GDS.HorizonReference
GDS.Location1
GDS.Location2
GDS.Location3
GDS.Id
GDS.AddHardware
GDS.MinimumElevationAngle
GDS.IonosphereModel
=
=
=
=
=
=
=
=
Earth;
Cartesian;
Ellipsoid;
-2353.621251;
-4641.341542;
3677.052370;
'33333';
{GDSTransmitter, ...
DSNAntenna, DSNReceiver};
= 7.0;
= 'IRI2007';
Next, we create and configure the MAD GroundStation resource, and associated Transmitter
resource.
%
Create MAD transmitter and ground station
Create Transmitter MADTransmitter
MADTransmitter.Frequency
= 7400;
%MHz.
MADTransmitter.PrimaryAntenna = DSNAntenna;
Create GroundStation MAD;
MAD.CentralBody
MAD.StateType
MAD.HorizonReference
MAD.Location1
MAD.Location2
MAD.Location3
MAD.Id
MAD.AddHardware
MAD.MinimumElevationAngle
MAD.IonosphereModel
=
=
=
=
=
=
=
=
Earth;
Cartesian;
Ellipsoid;
4849.519988;
-360.641653;
4114.504590;
'44444';
{MADTransmitter, ...
DSNAntenna, DSNReceiver};
= 7.0;
= 'IRI2007';
Note that for the GDS and MAD ground stations, we don’t re-use the DSNTransmitter resource
that we used for the CAN ground station. We do this so we can set the transmitter frequencies for
the different ground station to different values. Note that we didn’t do this in the Simulator tutorial.
This will only add a small error, however, since, because we are using a ramp table, the frequency set
on the Transmitter.Frequency field is only used to calculate media corrections.
Create Ground Station Error Models
It is well known that all measurement types have random noise and/or biases associated with them.
For GMAT, these affects are modelled using ground station error models. Since we have already
created the GroundStation object and its related hardware, we now create the ground station error
193
Tutorials
Orbit Estimation using DSN Range
and Doppler Data
models. Since we wish to form an orbit estimate using both range and Doppler data, we need to create
two error models as shown below, one for range measurements and one for Doppler measurements.
%
Create Ground station error
Create ErrorModel DSNrange;
DSNrange.Type
DSNrange.NoiseSigma
DSNrange.Bias
models
= 'Range_RU';
= 10.63;
= 0.0;
Create ErrorModel DSNdoppler;
DSNdoppler.Type
DSNdoppler.NoiseSigma
DSNdoppler.Bias
= 'Doppler_HZ';
= 0.0282;
= 0.0;
CAN.ErrorModels
GDS.ErrorModels
MAD.ErrorModels
= {DSNrange, DSNdoppler};
= {DSNrange, DSNdoppler};
= {DSNrange, DSNdoppler};
The script segment above is broken into three sections. The first section defines an ErrorModel
named DSNrange. The error model Type is Range_RU which indicates that it is an error model
for DSN range measurements. The 1 sigma standard deviation of the Gaussian white noise is set to
10.63 Range Units (RU) and the measurement bias is set to 0 RU.
The second section above defines an ErrorModel named DSNdoppler. The error model Type
is Doppler_HZ which indicates that it is an error model for DSN Doppler measurements. The 1
sigma standard deviation of the Gaussian white noise is set to 0.0282 Hz and the measurement bias
is set to 0 Hz. The range and Doppler NoiseSigma values above will be used to form measurement
weighting matrices used by the estimator algorithm.
The third section above attaches the two ErrorModel resources we have just created to the CAN,
GDS, and MAD GroundStation resources. Note that in GMAT, the measurement noise or bias is
defined on a per ground station basis. Thus, any range measurement error involving the CAN, GDS,
and MAD GroundStation is defined by the DSNRange ErrorModel and any Doppler measurement error involving the CAN, GDS, and MAD GroundStation is defined by the DSNdoppler
ErrorModel. Note that, if desired, we could have created 6 different ErrorModel resources, two
error models representing the two data types for 3 ground stations.
Define the types of measurements that will be processed
Now we will create and configure a TrackingFileSet resource. This resource defines the type of
data to be processed, the ground stations that will be used, and the file name of the input GMD
file which will contain the measurement data. Note that in order to just cut and paste from our
simulation tutorial, we name our resource DSNsimData. But, since, in this script, we are estimating,
perhaps a better name would have been DSNestData.
Create TrackingFileSet DSNsimData;
DSNsimData.AddTrackingConfig
DSNsimData.AddTrackingConfig
DSNsimData.AddTrackingConfig
DSNsimData.AddTrackingConfig
194
=
=
=
=
{{CAN,
{{CAN,
{{GDS,
{{GDS,
Sat,
Sat,
Sat,
Sat,
CAN},
CAN},
GDS},
GDS},
'DSNRange'};
'Doppler'};
'DSNRange'};
'Doppler'};
Orbit Estimation using DSN Range
and Doppler Data
Tutorials
DSNsimData.AddTrackingConfig
= {{MAD, Sat, MAD}, 'DSNRange'};
DSNsimData.AddTrackingConfig
= {{MAD, Sat, MAD}, 'Doppler'};
DSNsimData.FileName
= ...
{'../output/Simulate DSN Range and Doppler Data 3 weeks.gmd'};
DSNsimData.RampTable
= ...
{'../output/Simulate DSN Range and Doppler Data 3 weeks.rmp'};
DSNsimData.UseLightTime
DSNsimData.UseRelativityCorrection
DSNsimData.UseETminusTAI
= true;
= true;
= true;
The script lines above are broken into three sections. In the first section, the resource name, DSNsimData, is declared, the data types are defined, and the input GMD file and ramp table name
are specified. AddTrackingConfig is the field that is used to define the data types. The first AddTrackingConfig line tells GMAT to process DSN range two way measurements for the CAN to
Sat to CAN measurement strand. The second AddTrackingConfig line tells GMAT to process
DSN Doppler two way measurements for the CAN to Sat to CAN measurement strand. The remaining 4 AddTrackingConfig script lines tell GMAT to also process GDS and MAD range and
Doppler measurements. Note that the input GMD and ramp table files that we specified are files
that we created as part of the Simulate DSN Range and Doppler Data Tutorial. Don’t forget to
put these files in the GMAT “output” directory.
The second section above sets some processing parameters that apply to both the range and Doppler
measurements. We set UseLightTime to True in order to generate realistic computed, C, measurements that take into account the finite speed of light. The last two parameters in this section,
UseRelativityCorrection and UseETminusTAI, are set to True so that general relativistic corrections, as described in Moyer [2000], are applied to the light time equations.
Note that, in the simulation tutorial, we set two other DSNsimData fields, SimDopplerCountInterval and SimRangeModuloConstant. Since these fields only apply to simulations, there is no
need to set them here as their values would only be ignored.
Create and configure Force model and propagator
We now create and configure the force model and propagator that will be used for the simulation.
For this deep space drift away orbit, we naturally choose the Sun as our central body. Since we are
far away from all the planets, we use point mass gravity models and we include the effects of the
Sun, Earth, Moon, and most of the other planets. In addition, we model Solar Radiation Pressure
(SRP) affects and we include the effect of general relativity on the dynamics. The script segment
accomplishing this is shown below.
Create ForceModel Fm;
Create Propagator Prop;
Fm.CentralBody
Fm.PointMasses
Fm.SRP
Fm.RelativisticCorrection
Prop.FM
Prop.MinStep
= Sun;
= {Sun, Earth, Luna, Mars, Saturn, ...
Uranus, Mercury, Venus, Jupiter};
= On;
= On;
= Fm;
= 0;
195
Tutorials
Orbit Estimation using DSN Range
and Doppler Data
Prop.MaxStep
= 86400
We say a few words about our choice of minimum and maximum step sizes for our propagator. As
mentioned in the BatchEstimatorInv Help, it is recommended that if the ForceModel resource
associated with your propagator is using relative step control, i.e., ErrorControl = RSSStep,
then the minimum step size, MinStep, of your propagator should be set to 0. We have not directly
set the value of Fm.ErrorControl but since we know that, by default, its value is RSSStep, we set
Prop.MinStep equal to 0. For our deep space orbit, the dynamics are slowly changing and we want
our integrator to take large steps as long as the default accuracy error tolerance of approximately
1e-11 is maintained. Thus, we set our max step to 1 day. Finally, we note that for actual operational
missions, the user may want to use a more stringent accuracy error tolerance.
Create and configure BatchEstimatorInv object
As shown below, we create and configure the BatchEstimatorInv object used to define our estimation process.
Create BatchEstimatorInv bat
bat.ShowProgress
= true;
bat.ReportStyle
= Normal;
bat.ReportFile
= ...
'Orbit Estimation using DSN Range and Doppler Data.report';
bat.Measurements
= {DSNsimData}
bat.AbsoluteTol
= 0.001;
bat.RelativeTol
= 0.0001;
bat.MaximumIterations
= 10
bat.MaxConsecutiveDivergences = 3;
bat.Propagator
= Prop;
bat.ShowAllResiduals
= On;
bat.OLSEInitialRMSSigma
= 10000;
bat.OLSEMultiplicativeConstant = 3;
bat.OLSEAdditiveConstant
= 0;
bat.EstimationEpochFormat
= 'FromParticipants';
bat.InversionAlgorithm
= 'Internal';
bat.MatlabFile
= ...
'Orbit Estimation using DSN Range and Doppler Data.mat'
All of the fields above are described in BatchEstimatorInv Help but we describe them briefly here
as well. In the first script line above, we create a BatchEstimatorInv object, bat. In the next line,
we set the ShowProgress field to true so that detailed output of the batch estimator will be shown
in the message window.
In the third line, we set the ReportStyle to Normal. For the R2016A GMAT release, this is the only
report style that is available. In a future release, If we wanted to see additional data such as measurement partial derivatives, we would use the Verbose style. In the next line, we set the ReportFile field
to the name of our desired output file which by default is written to GMAT’s ‘output’ directory.
We set the Measurements field to the name of the TrackingFileSet resource we wish to use. Recall
that the TrackingFileSet, DSNsimData, that we created in the Define the types of measurements
that will be processed section defines the type of measurements that we wish to process. In our
196
Orbit Estimation using DSN Range
and Doppler Data
Tutorials
case, we wish to process DSN range and Doppler data associated with the CAN, GDS, and MAD
ground stations.
The next four fields, AbsoluteTol, RelativeTol, MaximumIterations, and MaxConsecutiveDivergences define the batch estimator convergence criteria. See the “Behavior of Convergence Criteria” discussion in the BatchEstimatorInv Help for complete details.
The next script line sets the Propagator field which specifies which Propagator object should be
used during estimation. We set this field to the Prop Propagator object which we created in the
Define the types of measurements that will be processed section.
In the 11th script line, we set the ShowAllResiduals field to true show that the observation residuals
plots, associated with the various ground stations, will be displayed
The next three script lines set fields, OLSEInitialRMSSigma, OLSEMultiplicativeConstant, and
OLSEAdditiveConstant, that are associated with GMAT’s Outer Loop Sigma Editing (OLSE) capability that is used to edit, i.e., remove, certain measurements so that they are not used to calculate the orbit estimate. See the “Behavior of Outer Loop Sigma Editing (OLSE)” discussion in the
BatchEstimatorInv Help for complete details.
Next, we set the EstimationEpochFormat field to 'FromParticipants’ which tells GMAT that the
epoch associated with the solve-for variables, in this case the Cartesian State of Sat, comes from the
value of Sat.Epoch which we have set to “19 Aug 2015 00:00:00.000 UTCG.”
Next, we set the InversionAlgorithm field to 'Internal' which specifies which algorithm GMAT
should use to invert the normal equations. There are two other inversion algorithms, 'Cholesky' or
'Schur' that we could optionally use.
Finally, we set the value of MatlabFile. This is the name of the MATLAB output file that will
be created, which, by default, is written to GMAT’s ‘output’ directory. This file can be read into
MATLAB to perform detailed calculations and analysis. The MATLAB file can only be created if
you have MATLAB installed and properly configured for use with GMAT.
Run the mission and analyze the results
The script segment used to run the mission is shown below.
BeginMissionSequence
RunEstimator bat
The first script line, BeginMissionSequence, is a required command which indicates that the
“Command” section of the GMAT script has begun. The second line of the script issues the RunEstimator command with the bat BatchEstimatorInv resource, defined in the Create and configure
BatchEstimatorInv object section, as an argument. This tells GMAT to perform the estimation using
parameters specified by the bat resource.
We have now completed all of our script segments. See the file, Orbit Estimation using DSN
Range and Doppler Data.script, for a listing of the entire script. We are now ready to run the
script. Hit the Save,Sync,Run button, (
). Given the amount of data we are processing, our
mission orbit, and our choice of force model, the script should finish execution in about 1-2 minutes.
197
Tutorials
Orbit Estimation using DSN Range
and Doppler Data
We analyze the results of this script in many ways. In the first subsection, we analyze the Message
window output. In the second subsection, we look at the plots of the observation residuals, and
in the third subsection, we analyze the batch estimation report. Finally, in the fourth subsection,
we discuss how the contents of the MATLAB output file can be used to analyze the results of our
estimation process.
Message Window Output
We first analyze the message window output focusing on the messages that may require some explanation. Follow along using Appendix A – GMAT Message Window Output where we have put
a full listing of the output. Soon into the message flow, we get a message telling us how many measurement records were read in.
Data file 'Simulate DSN Range and Doppler Data 3 weeks.gmd' has 1348
of 1348 records used for estimation.
The value of 1348 is the number of lines of measurement data in the GMD file listed above.
Next, the window output contains a description of the tracking configuration. The output below
confirms that we are processing range and Doppler data from the CAN, GDS, and MAD ground
stations.
List of tracking configurations (present in participant ID) for load
records from data file
'Simulate DSN Range and Doppler Data 3 weeks.gmd':
Config 0: {{22222,11111,22222},DSNRange}
Config 1: {{22222,11111,22222},Doppler}
Config 2: {{33333,11111,33333},DSNRange}
Config 3: {{33333,11111,33333},Doppler}
Config 4: {{44444,11111,44444},DSNRange}
Config 5: {{44444,11111,44444},Doppler}
Later on in the output, GMAT echoes out the a priori estimate that we input into the script.
The second and third fields, DSNRange and 9004, are just internal GMAT codes indicating the use
of DSN range (Trk 2-34 type 7) data.
a priori state:
Estimation Epoch:
27253.500417064603 A.1 modified Julian
27253.500416666666 TAI modified Julian
19 Aug 2015 00:00:00.000 UTCG
Sat.SunMJ2000Eq.X = -126544963
Sat.SunMJ2000Eq.Y = 61978518
Sat.SunMJ2000Eq.Z = 24133225
Sat.SunMJ2000Eq.VX = -13.789
Sat.SunMJ2000Eq.VY = -24.673
Sat.SunMJ2000Eq.VZ = -10.662
Next, GMAT outputs some data associated with the initial iteration of the Outer Loop Sigma Editing
(OLSE) process as shown below.
198
Orbit Estimation using DSN Range
and Doppler Data
Tutorials
Number of Records Removed Due To:
. No Computed Value Configuration Available : 0
. Out of Ramp Table Range
: 0
. Signal Blocked
: 0
. Initial RMS Sigma Filter : 0
. Outer-Loop Sigma Editor
: 0
Number of records used for estimation: 1348
As previously mentioned, the OLSE process can edit (i.e., remove) certain data from use as part of
the estimation algorithm. There are five conditions which could cause a data point to be edited. For
each condition, the output above specifies how many data points were edited. We now discuss the
meaning of the five conditions.
The first condition, “No Computed Value Configuration Available” means that GMAT has read
in some measurement data but no corresponding tracking configuration has been defined in the
GMAT script. Thus, GMAT has no way to form the computed, C, value of the measurement. For
example, this might happen if our script did not define a GroundStation object corresponding to
some data in the GMD file. Since we have defined everything we need to, no data points are edited
for this condition.
The second condition, “Out of Ramp Table Range,” means that while solving the light time equations, GMAT needs to know the transmit frequency, for some ground station, at a time that is
not covered by the ramp table specified in our TrackingFileSet resource, DSNsimData. Looking
at our input GMD file, we see that our measurement times range from 27253.500416666669 to
27274.500416666662 TAIMJD. Since our ramp table has a ramp record for all three ground stations
at 27252 TAIMJD which is about 1 ½ days before the first measurement and since our a priori Cartesian state estimate is fairly good, it makes sense that no measurements were edited for this condition.
The third condition, “Signal Blocked,” indicates that while taking into account its current estimate
of the state, GMAT calculates that a measurement for a certain measurement strand is not possible
because the signal is “blocked.” Actually, the signal does not have to blocked, it just has to violate
the minimum elevation angle constraint associated with a given ground station. Consider a GDS to
Sat to GDS range two way range measurement at given time. If the GDS to Sat elevation angle was
6 degrees, the measurement would be edited out since the minimum elevation angle, as specified by
the GDS.MinimumElevationAngle field, is set at 7 degrees. Since, in our simulation, we specified
that only data meeting this 7 degree constraint should be written out, it is plausible that no data were
edited because of this condition.
The fourth condition, “Initial RMS Sigma Filter,” corresponds to GMAT’s OLSE processing for
the initial iteration. As mentioned before, you can find a complete description of the OLSE in the
“Behavior of Outer Loop Sigma Editing (OLSE)” discussion in the BatchEstimatorInv Help. As
described in the Help, for the initial iteration, data is edited if
|Weighted Measurement Residual| > OLSEInitialRMSSigma
where the Weighted Measurement Residual for a given measurement is given by
(O-C)/NoiseSigma
and where NoiseSigma are inputs that we set when we created the various ErrorModel resources.
199
Tutorials
Orbit Estimation using DSN Range
and Doppler Data
We note that for a good orbit solution, the Weighted Measurement Residual has a value of approximately one. Since our a priori state estimate is not that far off from the truth and since we have set
OLSEInitialRMSSigma to a very large value of 10,000, we do not expect any data to be edited
for this condition.
The fifth condition, “Outer-Loop Sigma Editor,” corresponds to GMAT’s OLSE processing for the
second or later iteration. Since the output we are analyzing is for the initial iteration of the batch
estimator, the number of data points edited because of this condition is 0. We will discuss the OLSE
processing for the second or later iterations when we analyze the output for a later iteration.
WeightedRMS residuals for this iteration : 1459.94235975
BestRMS residuals for this iteration
: 1459.94235975
PredictedRMS residuals for next iteration: 1.01539521333
The first output line above gives the weighted RMS calculated when the estimate of the state is the
input a priori state (i.e., the 0th iteration state). The weighted RMS value of approximately 1460 is
significantly far away from the value of 1 associated with a good orbit solution. The second output
line gives the best (smallest) weighted RMS value for all of the iterations. Since this is our initial
iteration, the value of the BestRMS is the same as the WeightedRMS. The third output line is the
predicted weighted RMS value for the next iteration. Because of the random noise involved in generating the simulated input data, the numbers you see may differ from that above.
Next, GMAT outputs the state associated with the first iteration of the batch estimator. Let’s define
what we mean by iteration. The state at iteration ‘n’ is the state after GMAT has solved the so-called
normal equations (e.g., Eq. 4.3.22 or 4.3.25 in Tapley [2004]) ‘n’ successive times. By convention, the
state at iteration 0 is the input a priori state.
-----------------------------------------------------Iteration 1
Current estimated state:
Estimation Epoch:
27253.500417064603 A.1 modified Julian
27253.500416666666 TAI modified Julian
19 Aug 2015 00:00:00.000 UTCG
Sat.SunMJ2000Eq.X = -126544968.377
Sat.SunMJ2000Eq.Y = 61978514.8777
Sat.SunMJ2000Eq.Z = 24133217.2547
Sat.SunMJ2000Eq.VX = -13.7889998632
Sat.SunMJ2000Eq.VY = -24.6730006664
Sat.SunMJ2000Eq.VZ = -10.6619986007
Next, GMAT outputs statistics on how many data points were edited for this iteration.
Number of Records Removed Due To:
. No Computed Value Configuration Available : 0
. Out of Ramp Table Range
: 0
. Signal Blocked : 0
. Initial RMS Sigma Filter : 0
. Outer-Loop Sigma Editor : 2
Number of records used for estimation: 1346
200
Orbit Estimation using DSN Range
and Doppler Data
Tutorials
For the same reasons we discussed for the initial 0th iteration, as expected, no data points were edited
because “No Computed Value Configuration Available” or because a requested frequency was “Out
of Ramp Table Range.” Also, for the same reasons discussed for the 0th iteration, it is plausible that
no data points were edited for this iteration because of signal blockage. Note that there are no data
points edited because of the “Initial RMS Sigma Filter” condition. This is as expected because this
condition only edits data on the initial 0th iteration. Finally, we note that 2 data points out of 1348
data points are edited because of the OLSE condition. As discussed in the “Behavior of Outer Loop
Sigma Editing (OLSE)” section in the BatchEstimatorInv Help,” data is edited if
|Weighted Measurement Residual| > OLSEMultiplicativeConstant * WRMSP + OLSEAdditiveConstant
where
WRMSP is the predicted weighted RMS calculated at the end of the previous iteration.
In the Create and configure BatchEstimatorInv object section, we chose OLSEMultiplicativeConstant = 3 and OLSEAdditiveConstant = 0 and thus the equation above becomes
|Weighted Measurement Residual| > 3 * WRMSP
It is a good sign that only 2 of 1348, or 0.15 % of the data is edited out. If too much data is edited
out, even if you have a good weighted RMS value, it indicates that you may have a problem with
your state estimate. Next, GMAT outputs some root mean square, (RMS), statistical data associated
with iteration 1.
WeightedRMS residuals for this iteration : 1.00807187051
BestRMS residuals for this iteration
: 1.00807187051
PredictedRMS residuals for next iteration: 1.00804237273
The first output line above gives the weighted RMS calculated when the estimate of the state is the
iteration 1 state. The weighted RMS value of 1.00807187051 is very close to the value of 1 associated
with a good orbit solution. The second output line gives the best (smallest) weighted RMS value for
all of the iterations. Since this iteration 1 WeightedRMS value is the best so far, BestRMS is set to
the current WeightedRMS value. The third output line is the predicted weighted RMS value for the
next iteration. Note that the RMS values calculated above only use data points that are used to form
the state estimate. Thus, the edited points are not used to calculate the RMS.
Because the predicted WeightedRMS value is very close to the BestRMS value, GMAT, as shown in
the output below, concludes that the estimation process has converged. As previously mentioned, see
the “Behavior of Convergence Criteria” discussion in the BatchEstimatorInv Help for complete
details.
This iteration is converged due to relative convergence criteria.
********************************************************
*** Estimating Completed in 2 iterations
********************************************************
Estimation converged!
|1 - RMSP/RMSB| = | 1- 1.00804 / 1.00807| = 2.92616e-005 is
201
Tutorials
Orbit Estimation using DSN Range
and Doppler Data
less than RelativeTol, 0.0001
GMAT then outputs the final, iteration 2, state. Note that GMAT does not actually calculate the
weighted RMS associated with this state but we assume that it is close to the predicted value of
1.00804237273 that was previously output.
Final Estimated State:
Estimation Epoch:
27253.500417064603 A.1 modified Julian
27253.500416666666 TAI modified Julian
19 Aug 2015 00:00:00.000 UTCG
Sat.SunMJ2000Eq.X = -126544968.759
Sat.SunMJ2000Eq.Y = 61978514.3889
Sat.SunMJ2000Eq.Z = 24133216.7847
Sat.SunMJ2000Eq.VX = -13.7889997238
Sat.SunMJ2000Eq.VY = -24.673000621
Sat.SunMJ2000Eq.VZ = -10.6619988668
Finally, GMAT outputs the final Cartesian state error covariance matrix and correlation matrix, as
well as the time required to complete this script.
Final Covariance Matrix:
6.566855211518e+000
1.044634082751e+001
3.112865361595e+000
-2.345908159193e-006
5.035500497713e-007
1.602400700119e-006
1.044634165793e+001
2.043155461343e+001
-4.258297445960e+000
-3.704076213842e-006
2.022939026968e-007
3.971536117909e-006
3.112863356104e+000
-4.258301029878e+000
2.371732979013e+001
-1.178974284159e-006
1.683977056710e-006
-2.674174002075e-006
-2.345908150453e-006
-3.704075903144e-006
-1.178974996784e-006
8.386165742100e-013
-1.658563826712e-013
-6.047842762516e-013
5.035500518048e-007
2.022938490903e-007
1.683977194948e-006
-1.658563839962e-013
1.032575255469e-012
-2.190676053038e-012
1.602400702334e-006
3.971535902921e-006
-2.674173473312e-006
-6.047842793431e-013
-2.190676053421e-012
5.776276322091e-012
0.901851016006
1.000000000000
-0.193442720520
-0.894844322236
0.044042425647
0.365581179531
0.249429858518
-0.193442883328
1.000000000000
-0.264356330820
0.340284695741
-0.228471896026
-0.999655967713
-0.894844247176
-0.264356490609
1.000000000000
-0.178233613372
-0.274786119102
0.193376220513
0.044042413976
0.340284723675
-0.178233614796
1.000000000000
-0.897001819239
0.260176714954
0.365581159741
-0.228471850851
-0.274786120507
-0.897001819395
1.000000000000
Final Correlation Matrix:
1.000000000000
0.901850944314
0.249430019216
-0.999655971438
0.193376219732
0.260176714594
********************************************************
Mission run completed.
===> Total Run Time: 85.739000 seconds
========================================
Plots of Observation Residuals
GMAT creates plots on a per iteration, per ground station, and per measurement type basis. We
elaborate on what this means. When the script first runs, the first plots that show up are the 0th iteration residuals. This means that when calculating the ‘O-C’ observation residual, GMAT calculates
the Computed, C, value of the residual using the a priori state. As shown in Appendix B – Zeroth
Iteration Plots of Observation Residuals, there are 6 of these 0th iteration residual plots. For each of
the 3 stations, there is one plot of the range residuals and one plot of the Doppler residuals. After
iteration 1 processing is complete, GMAT outputs the iteration 1 residuals as shown in Appendix C
– First Iteration Plots of Observation Residuals. As previously mentioned, although for this script,
GMAT takes two iterations to converge, the actual iteration 2 residuals are neither calculated nor
plotted. DSN_Estimation_Create_and_configure_the_Ground_Station_and_related_parameters
202
Orbit Estimation using DSN Range
and Doppler Data
Tutorials
We now analyze the CAN range and Doppler residuals. For the 0th iteration, the range residuals
vary from approximately 11,000 to 31,000 RU. These residuals are this large because our a priori
estimate of the state was deliberately perturbed from the truth. There are multiple indicators on
this graph that indicate that GMAT has not yet converged. First, the residuals have an approximate
linear structure. If you have modeled the dynamics and measurements correctly, the plots should
have a random appearance with no structure. Additionally, the residuals are biased, i.e., they do not
have zero mean. For a well modeled system, the mean value of the residuals should be near zero.
Finally, the magnitude of the range residuals is significantly too large. Recall that in the Create and
configure the Ground Station and related parameters section, we set the 1 sigma measurement noise
for the CAN range measurements to 10.63 RU. Thus, for a large sample of measurements, we expect,
roughly, that the vast majority of measurements will lie between the values of approximately -32 and
+32 RU. Taking a look at the 1st iteration CAN range residuals, this is, approximately, what we get.
The 0th iteration CAN Doppler residuals range from approximately 0.0050 to 0.01535 Hz. As was
the case for the range 0th iteration residuals, the fact that the Doppler residuals are biased indicates
that GMAT has not yet converged. Recall that in the Create and configure the Ground Station and
related parameters section, we set the 1 sigma measurement noise for the CAN Doppler measurements to 0.0282 Hz. Thus, for a large sample of measurements, we expect, roughly, that the vast
majority of measurements will lie between the values of approximately -0.0846 and +0.0846 RU.
Taking a look at the 1st iteration CAN Doppler residuals, this is, approximately, what we get.
There is one important detail on these graphs that you should be aware of. GMAT only plots the
residuals for data points that are actually used to calculate the solution. Recall that for iteration 0,
all 1348 of 1348 total measurements were used to calculate the orbit state, i.e., no data points were
edited. Thus, if you counted up all the data points on the 6 iteration 0 plots, you would find 1348
points. The situation is different for the 1st iteration. Recall that for iteration 1, 1346 of 1348 total
measurements were used to calculate the orbit state, i.e., 2 data points were edited. Thus, if you
counted up all the data points on the 6 iteration 1 plots, you would find 1346 points. If you wish
to generate plots that contain both non-edited and edited measurements, you will need to generate
them yourself using the MATLAB output file as discussed in the Matlab Output File section.
We note that the graphs have some interactive features. Hover your mouse over the graph of interest
and then right click. You will see that you have four options. You can toggle both the grid lines and
the Legend on and off. You can also export the graph data to a text file, and finally, you can export
the graph image to a bmp file.
Batch Estimator Output Report
When we created our BatchEstimatorInv resource, bat, in the Create and configure BatchEstimatorInv object section, we specified that the output file name would be 'Orbit Estimation using DSN
Range and Doppler Data.report. Go to GMAT’s ‘output’ directory and open this file, preferably
using an editor such as Notepad++ where you can easily scroll across the rows of data.
The first approximately 150 lines of the report are mainly an echo of the parameters we input into
the script such as initial spacecraft state, force model, propagator settings, measurement types to be
processed, etc.
After this echo of the input data, the output report contains measurement residuals associated with
the initial 0th iteration. Search the file for the words, ‘ITERATION 0: MEASUREMENT RESIDUALS’ to find the location of where the relevant output begins. This output sections contains
203
Tutorials
Orbit Estimation using DSN Range
and Doppler Data
information on all of the measurements, both non-edited and edited, that can possibly be used in
the estimation process. Each row of data corresponds to one measurement. For each measurement,
the output tells you the following
•
•
•
•
•
•
•
•
•
•
Iteration Number
Record Number
Epoch in UTC Gregorian format
Observation type. ‘DSNRange’ corresponds to DSN range and ‘Doppler’ corresponds to DSN
Doppler.
Participants. For example, ‘22222,11111,22222’ tells you that your measurement comes from a
CAN to Sat to CAN link.
Edit Criteria.
Observed Value (O)
Computed Value (C)
Observation Residual (O-C)
Elevation Angle
We have previously discussed the edit criteria. In particular, we discussed the various reasons why
data might be edited. If the edit criteria shown in the output is ‘-,’ this means that the data was not
edited and the data was used, for this iteration, to calculate a state estimate.
Note that if the elevation angle of any of the measurements is below our input criteria of 7 degrees,
then the measurement would be edited because the signal would be considered to be “blocked.”
For range data, we would see Bn where n is an integer specifying the leg number. For our two way
range data type, we have two legs, the uplink leg represented by the integer, 1, and the downlink
leg, represented by the integer 2. Thus, if we saw “B1” in this field, this would mean that the signal
was blocked for the uplink leg. Correspondingly, for Doppler data, we would also see Bn, but the
integer n would be 1 or 2 depending upon whether the blockage occurred in the start path (n=1)
or the end path (n=2).
After all of the individual iteration 0 residuals are printed out, four different iteration 0 observation
summary reports, as shown below, are printed out.
•
•
•
•
Observation Summary by Station and Data Type
Observation Summary by Data Type and Station
Observation Summary by Station
Observation Summary by Data Type
After all of the observation summaries are printed out, the updated state and covariance information,
obtained by processing the previous residual information, are printed out. The output also contains
statistical information about how much the individual components of the state estimate have changed
for this iteration.
At this point, the output content repeats itself for the next iteration. The new state estimate is used
to calculate new residuals and the process starts all over again. The process stops when the estimator
has either converged or diverged.
We now give an example of how this report can be used. In the Message Window Output section,
we noted that, for iteration 1, two measurements were edited because of the OLSE criteria. Let’s
investigate this in more detail. What type of data was edited? From what station? Could there be a
problem with this data type at this station? We look at the ‘Observation Summary by Station and
204
Orbit Estimation using DSN Range
and Doppler Data
Tutorials
Data Type’ for iteration 1. We see that one range measurement from the GDS station and one range
measurement from the MAD station was edited. The mean residual and 1 sigma standard deviation
for GDS range measurements was -0.828187 and 10.595392 RU, respectively. The mean residual
and 1 sigma standard deviation for MAD range measurements was 0.976758 and 11.047855 RU,
respectively.
Now that we know that the issue was with GDS and MAD range measurements, we look at the
detailed residual output, for iteration 1, to determine the time these measurements occurred. We can
search for the OLSE keyword to help do this. We determine that a GDS range measurement was
edited at 07 Sep 2015 19:00:00.000 UTCG and that it had an observation residual of -32.432373 RU.
This is just a bit beyond the 3 sigma value and we conclude that there is no real problem with the
GDS range measurements. This is just normal statistical variation.
We also determine that a MAD range measurement was edited at 31 Aug 2015 11:00:00.000 UTCG
and that it had an observation residual of -33.497559 RU. Again, this is just a bit beyond the 3 sigma
value and we conclude that there is no real problem with the MAD range measurements. We remind
you, that when you do your run, you may have a different number of data points edited. This is
because, when you do your simulation, GMAT uses a random number generator and you will be
using a different data set.
Matlab Output File
In the Create and configure BatchEstimatorInv object section, when we created our BatchEstimatorInv resource, bat, we chose our MATLAB output file name, 'Orbit Estimation using DSN
Range and Doppler Data.mat.' By default, this file is created in GMAT’s ‘output’ directory.
This file will only be created if you have MATLAB installed and properly configured for use with
GMAT.
Start up a MATLAB session. Change the directory to your GMAT ‘output’ directory and then type
the following at the MATLAB command prompt.
>> load 'Orbit Estimation using DSN Range and Doppler Data.mat'
After the file has loaded, type the following command to obtain a list of available variable names
inside this file.
>> whos
You should see something similar to the following:
>> whos
Name
Iteration0
Iteration1
Iteration2
Size
Bytes
Class
1x1
1x1
1x1
847660
847690
847696
struct
struct
struct
Attributes
You may see more or fewer iterations depending on your run. Each iteration variable is a structure
containing the following arrays:
Status
Observation status flag, 1 = observation is good/
useable
205
Tutorials
Orbit Estimation using DSN Range
and Doppler Data
IterationNumber
The iteration number. This matches the iteration
number in the structure name.
Epoch
The TAIModJulian time tag of each observation,
computed value, and residual
Observed
The observed value (from the GMD file) in
Range Units or Hertz
Calculated
The predicted observation, in Range Units or
Hertz, computed by GMAT using the force modeling specified in the batch estimator propagator
ObsMinusCalculated
The observation residual, in Range Units or
Hertz
Elevation
The computed elevation of the observation, in
degrees
Frequency
The transmit frequency at the time of the observation, in Hertz
FrequencyBand
The frequency band of the observation. See the
TrackingFileSet help for a list of frequency
band indicators.
DopplerCountInterval
The Doppler count interval in seconds, for
Doppler observations. Set to -1 for range observations.
Participants
For each observation, a comma-separated string
identifying the transmit station, tracked object,
and receive station in order
Type
A string identifying the observation type, DSNRange or Doppler
UTCGregorian
The UTCGregorian epoch string of each observation
ObsEditFlag
The editing status flag for each observation. N
= not edited, U = no computed value configuration available, R = out of ramp table range, B =
blocked by elevation edit criteria, IRMS = initial
RMS sigma edit, OLSE = outer-loop sigma edit
Any unset or uncomputed values are set to -1. You can use these arrays to perform custom plots
and statistical analysis using MATLAB. For example, to produce a plot of all range residuals from
the final iteration, you can do the following:
>> I = find(strcmp(Iteration2.Type, 'DSNRange'));
>> plot(Iteration2.Epoch(I), Iteration2.ObsMinusCalc(I), 'go');
References
GTDS [1989]
206
Goddard Trajectory Mathematical Theory, Revision 1, Edited by A. Long, J. Cappellari, et al., Computer Sciences Corporation, FDD, FDD-552-89-0001, July
1989.
Orbit Estimation using DSN Range
and Doppler Data
Tutorials
GTDS [2007]
Goddard Trajectory Determination System User’s Guide, National Aeronautics
and Space Administration, GSFC, Greenbelt, MD, MOMS-FD-UG-0346, July
2007
Moyer [2000]
Moyer, Theodore D., Formulation for Observed and Computed Values of Deep
Space Network Data Types for Navigation (JPL Publication 00-7), Jet Propulsion
Laboratory, California Institute of Technology, October 2000.
Tapley [2004]
Tapley, Schutz, Born, Statistical Orbit Determination, Elsevier, 2004
Appendix A – GMAT Message Window Output
Running mission...
Data file 'Simulate DSN Range and Doppler Data 3 weeks.gmd' has 1348
of 1348 records used for estimation.
Total number of load records : 1348
List of tracking configurations (present in participant ID) for load
records from data file
'Simulate DSN Range and Doppler Data 3 weeks.gmd':
Config
Config
Config
Config
Config
Config
0:
1:
2:
3:
4:
5:
{{22222,11111,22222},DSNRange}
{{22222,11111,22222},Doppler}
{{33333,11111,33333},DSNRange}
{{33333,11111,33333},Doppler}
{{44444,11111,44444},DSNRange}
{{44444,11111,44444},Doppler}
****
No tracking configuration was generated because the tracking
configuration is defined in the script.
********************************************************
*** Performing Estimation (using "bat")
***
********************************************************
a priori state:
Estimation Epoch:
27253.500417064603 A.1 modified Julian
27253.500416666666 TAI modified Julian
19 Aug 2015 00:00:00.000 UTCG
Sat.SunMJ2000Eq.X = -126544963
Sat.SunMJ2000Eq.Y = 61978518
Sat.SunMJ2000Eq.Z = 24133225
Sat.SunMJ2000Eq.VX = -13.789
Sat.SunMJ2000Eq.VY = -24.673
Sat.SunMJ2000Eq.VZ = -10.662
Number of Records Removed Due To:
207
Tutorials
Orbit Estimation using DSN Range
and Doppler Data
. No Computed Value Configuration Available : 0
. Out of Ramp Table Range
: 0
. Signal Blocked : 0
. Initial RMS Sigma Filter : 0
. Outer-Loop Sigma Editor : 0
Number of records used for estimation: 1348
WeightedRMS residuals for this iteration : 1459.94235975
BestRMS residuals for this iteration
: 1459.94235975
PredictedRMS residuals for next iteration: 1.01539521333
-----------------------------------------------------Iteration 1
Current estimated state:
Estimation Epoch:
27253.500417064603 A.1 modified Julian
27253.500416666666 TAI modified Julian
19 Aug 2015 00:00:00.000 UTCG
Sat.SunMJ2000Eq.X = -126544968.377
Sat.SunMJ2000Eq.Y = 61978514.8777
Sat.SunMJ2000Eq.Z = 24133217.2547
Sat.SunMJ2000Eq.VX = -13.7889998632
Sat.SunMJ2000Eq.VY = -24.6730006664
Sat.SunMJ2000Eq.VZ = -10.6619986007
Number of Records Removed Due To:
. No Computed Value Configuration Available
. Out of Ramp Table Range
. Signal Blocked
. Initial RMS Sigma Filter
. Outer-Loop Sigma Editor
Number of records used for estimation
: 0
: 0
: 0
: 0
: 2
:1346
WeightedRMS residuals for this iteration : 1.00807187051
BestRMS residuals for this iteration
: 1.00807187051
PredictedRMS residuals for next iteration: 1.00804237273
This iteration is converged due to relative convergence criteria.
********************************************************
*** Estimating Completed in 2 iterations
********************************************************
Estimation converged!
|1 - RMSP/RMSB| = | 1- 1.00804 / 1.00807| = 2.92616e-005 is
less than RelativeTol, 0.0001
Final Estimated State:
208
Orbit Estimation using DSN Range
and Doppler Data
Tutorials
Estimation Epoch:
27253.500417064603 A.1 modified Julian
27253.500416666666 TAI modified Julian
19 Aug 2015 00:00:00.000 UTCG
Sat.SunMJ2000Eq.X = -126544968.759
Sat.SunMJ2000Eq.Y = 61978514.3889
Sat.SunMJ2000Eq.Z = 24133216.7847
Sat.SunMJ2000Eq.VX = -13.7889997238
Sat.SunMJ2000Eq.VY = -24.673000621
Sat.SunMJ2000Eq.VZ = -10.6619988668
Final Covariance Matrix:
6.566855211518e+000
1.044634082751e+001
3.112865361595e+000
-2.345908159193e-006
5.035500497713e-007
1.602400700119e-006
1.044634165793e+001
2.043155461343e+001
-4.258297445960e+000
-3.704076213842e-006
2.022939026968e-007
3.971536117909e-006
3.112863356104e+000
-4.258301029878e+000
2.371732979013e+001
-1.178974284159e-006
1.683977056710e-006
-2.674174002075e-006
-2.345908150453e-006
-3.704075903144e-006
-1.178974996784e-006
8.386165742100e-013
-1.658563826712e-013
-6.047842762516e-013
5.035500518048e-007
2.022938490903e-007
1.683977194948e-006
-1.658563839962e-013
1.032575255469e-012
-2.190676053038e-012
1.602400702334e-006
3.971535902921e-006
-2.674173473312e-006
-6.047842793431e-013
-2.190676053421e-012
5.776276322091e-012
0.901851016006
1.000000000000
-0.193442720520
-0.894844322236
0.044042425647
0.365581179531
0.249429858518
-0.193442883328
1.000000000000
-0.264356330820
0.340284695741
-0.228471896026
-0.999655967713
-0.894844247176
-0.264356490609
1.000000000000
-0.178233613372
-0.274786119102
0.193376220513
0.044042413976
0.340284723675
-0.178233614796
1.000000000000
-0.897001819239
0.260176714954
0.365581159741
-0.228471850851
-0.274786120507
-0.897001819395
1.000000000000
Final Correlation Matrix:
1.000000000000
0.901850944314
0.249430019216
-0.999655971438
0.193376219732
0.260176714594
********************************************************
Mission run completed.
===> Total Run Time: 85.739000 seconds
========================================
Appendix B – Zeroth Iteration Plots of Observation Residuals
209
Tutorials
Orbit Estimation using DSN Range
and Doppler Data
Appendix C – First Iteration Plots of Observation Residuals
210
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.
Reference Guide
Resources
Table of Contents
Antenna ........................................................................................................................
Array .............................................................................................................................
Barycenter .....................................................................................................................
BatchEstimatorInv .........................................................................................................
CelestialBody .................................................................................................................
CoordinateSystem ...........................................................................................................
ContactLocator ..............................................................................................................
DifferentialCorrector ......................................................................................................
ElectricTank ..................................................................................................................
ElectricThruster .............................................................................................................
EclipseLocator ...............................................................................................................
EphemerisFile ................................................................................................................
ErrorModel ...................................................................................................................
FileInterface ...................................................................................................................
FiniteBurn .....................................................................................................................
FminconOptimizer .........................................................................................................
Formation .....................................................................................................................
ChemicalTank ................................................................................................................
GMATFunction .............................................................................................................
GroundStation ...............................................................................................................
GroundTrackPlot ...........................................................................................................
ImpulsiveBurn ...............................................................................................................
LibrationPoint ................................................................................................................
MatlabFunction ..............................................................................................................
NuclearPowerSystem ......................................................................................................
OrbitView .....................................................................................................................
Propagator .....................................................................................................................
Receiver .........................................................................................................................
ReportFile .....................................................................................................................
Simulator .......................................................................................................................
SNOPT .........................................................................................................................
SolarPowerSystem ..........................................................................................................
SolarSystem ...................................................................................................................
Spacecraft ......................................................................................................................
Spacecraft Attitude .........................................................................................................
Spacecraft Ballistic/Mass Properties .................................................................................
Spacecraft Epoch ...........................................................................................................
Spacecraft Hardware .......................................................................................................
Spacecraft Navigation .....................................................................................................
Spacecraft Orbit State .....................................................................................................
Spacecraft Visualization Properties ...................................................................................
StatisticsAcceptFilter .......................................................................................................
StatisticsRejectFilter ........................................................................................................
215
217
221
227
235
253
273
285
291
295
307
317
331
335
339
345
351
355
365
381
391
399
407
413
417
421
445
481
483
493
497
503
509
515
517
551
561
571
575
579
609
615
619
213
Reference Guide
Resources
String ............................................................................................................................
TrackingFileSet ...............................................................................................................
Transmitter ....................................................................................................................
Transponder ..................................................................................................................
ChemicalThruster ...........................................................................................................
Variable .........................................................................................................................
VF13ad .........................................................................................................................
XYPlot ..........................................................................................................................
214
623
625
633
635
639
659
663
667
Reference Guide
Antenna
Transmits or receives an RF signal.
Description
A number of GMAT resources, GroundStation, Transponder, Receiver, and Transmitter, use an
Antenna resource to transmit and/or receive RF signals.
See Also: GroundStation, Transponder, Receiver, Transmitter
Fields
There are no fields for the Antenna resource.
Examples
This example shows how the Antenna resource is used.
Create Antenna SatTranponderAntenna DSNReceiverAntenna DSNTransmitterAntenna;
Create Transponder SatTransponder;
SatTransponder.PrimaryAntenna
= SatTranponderAntenna
Create Spacecraft Sat
Sat.AddHardware
= {SatTransponder, SatTranponderAntenna};
Create Transmitter DSNTransmitter
DSNTransmitter.PrimaryAntenna
= DSNTransmitterAntenna
Create Receiver DSNReceiver
DSNReceiver.PrimaryAntenna
= DSNReceiverAntenna;
Create GroundStation DSN;
DSN.AddHardware
= ...
{DSNTransmitter, DSNReceiver, DSNTransmitterAntenna, DSNReceiverAntenna};
BeginMissionSequence;
Since the Antenna resource currently has no fields and thus has no function, for this GMAT release,
we only need to create one Antenna resource that can be used multiple times. Thus, the example
above simplifies as shown below.
Create Antenna GenericAntenna;
Create Transponder SatTransponder;
SatTransponder.PrimaryAntenna
= GenericAntenna
Create Spacecraft Sat
Sat.AddHardware
= {SatTransponder, GenericAntenna};
Create Transmitter DSNTransmitter
DSNTransmitter.PrimaryAntenna
= GenericAntenna
Create Receiver DSNReceiver
DSNReceiver.PrimaryAntenna
= GenericAntenna;
215
Reference Guide
Antenna
Create GroundStation DSN;
DSN.AddHardware
= ...
{DSNTransmitter, DSNReceiver, GenericAntenna};
BeginMissionSequence;
216
Reference Guide
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.
Field
Description
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
Allowed Values
Access
Default Value
Units
Interfaces
Integer
1 ≤ rows ≤ 1000
set
1
N/A
GUI, script
217
Reference Guide
Array
Field
Description
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
Allowed Values
Access
Default Value
Units
Interfaces
value
Integer
1 ≤ columns ≤ 1000
set
1
N/A
GUI, script
The value of the array element being addressed.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
Real number
-∞ < value < ∞
set, get
0.0
N/A
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.
218
Array
Reference Guide
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
Create
a(1) =
a(2) =
a(3) =
a row vector with 3
Array a[3]
1
% same as a(1,
2
% same as a(1,
3
% same as a(1,
elements
1) = 1
2) = 2
3) = 3
219
Reference Guide
% 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
220
Array
Reference Guide
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, Color
Fields
Field
Description
BodyNames
The list of CelestialBody resources included in the Barycenter. Providing
empty brackets sets the bodies to the default list described below.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
OrbitColor
String array
array of celestial bodies. You cannot add bodies to
the built-in SolarySystemBarycenter resource.
A CelestialBody can only appear once in the BodyNames list.
set
Earth, Luna
N/A
GUI, script
Allows you to set available colors on user-defined Barycenter object orbits. The barycenter orbits are drawn using the OrbitView graphics resource. Colors on Barycenter object can be set through a string or an integer array. For example: Setting a barycenter's orbit color to red can be
done in the following two ways: Barycenter.OrbitColor = Red or
Barycenter.OrbitColor = [255 0 0]. This field can be modified
in the Mission Sequence as well.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
Integer Array or String
Any color available from the Orbit Color Picker in
GUI. Valid predefined color name or RGB triplet
value between 0 and 255.
set
Gold
N/A
GUI, script
221
Reference Guide
Barycenter
Field
Description
TargetColor
Allows you to select available colors for Barycenter object's perturbing orbital trajectories that are drawn during iterative processes such
as Differential Correction or Optimization. The target color can be
identified through a string or an integer array. For example: Setting
a barycenter's perturbing trajectory color to yellow can be done in
following two ways: Barycenter.TargetColor = Yellow or
Barycenter.TargetColor = [255 255 0]. This field can be modified in the Mission Sequence as well.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
Integer Array or String
Any color available from the Orbit Color Picker in
GUI. Valid predefined color name or RGB triplet
value between 0 and 255.
set
DarkGray
N/A
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 ap222
Barycenter
Reference Guide
pear 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.
223
Reference Guide
Barycenter
Setting Colors On Barycenter Orbits
GMAT allows you to assign colors to barycenter orbits that are drawn using the OrbitView graphics
resource. GMAT also allows you to assign colors to perturbing barycenter orbital trajectories which
are drawn during iterative processes such as differential correction or optimization. The Barycenter
object's OrbitColor and TargetColor fields are used to assign colors to both orbital and perturbing
trajectories. See the Fields section to learn more about these two fields. Also see Color documentation
for discussion and examples on how to set colors on a barycenter orbit.
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
224
Barycenter
Reference Guide
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
225
226
Reference Guide
BatchEstimatorInv
A batch least squares estimator
Description
A batch least squares estimator is a method for obtaining an estimate for a parameter vector, x0,
such that a performance index, which is a function of that parameter, J = J(x0), is minimized. For
our application, x0 typically includes the spacecraft position and velocity at a specific epoch and the
performance index is a weighted sum of the square of the measurement residuals.
See Also: TrackingFileSet, RunEstimator
Fields
Field
Description
AbsoluteTol
Absolute Weighted RMS convergence criteria tolerance
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
EstimationEpoch
Estimation Epoch. This is the epoch associated with the "solve-fors." For
release R2016A, this epoch comes from the participants defined in the
Measurements field. In later releases, additional options will be allowed.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
EstimationEpochFormat
Real
Real > 0
set
0.001
dimensionless
script
String
'FromParticipants'
set
'FromParticipants'
N/A
script
Estimation Epoch format. This is the desired input format for the EstimationEpoch field. For release R2016A, the only allowed value is
'FromParticipants' which means that the EstimationEpoch comes from
the participants defined in the Measurements field. In later releases, additional options will be allowed.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
String
'FromParticipants'
set
'FromParticipants'
N/A
script
227
Reference Guide
BatchEstimatorInv
Field
Description
InverseAlgorithm
Algorithm used to invert the normal equations
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
MatlabFile
File name for the output MATLAB file. A value of None means that no
MATLAB file will be output.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
MaxConsecutiveDivergences
integer
any positive integer
set
15
N/A
script
Specifies a list of measurements used for batch estimation
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
228
integer
any positive integer
set
3
N/A
script
Specifies maximum number of iterations allowed for batch estimation
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
Measurements
String
Any valid file name.
set
None
N/A
script
Specifies maximum number of consecutive diverging iterations allowed
before batch estimation processing is stopped
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
MaximumIterations
String
Internal, Cholesky, Schur
set
Internal
N/A
script
ObjectArray
valid TrackingFileSet object
set
empty list
N/A
script
BatchEstimatorInv
Reference Guide
Field
Description
OLSEAdditiveConstant
Additive constant used for outer loop sigma editing (OLSE)
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
Real
any real number
set
0.0
dimensionless
script
OLSEInitialRMSSig- Initial predicted root-mean-square value used for outer loop sigma editing
ma
(OLSE)
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
Real
Real > 0.0
set
3000.0
dimensionless
script
OLSEMultiplicative- Multiplicative constant used for outer loop sigma editing (OLSE)
Constant
Data Type
Real
Allowed Values
Real > 0.0
Access
set
Default Value
3.0
Units
dimensionless
Interfaces
script
Propagator
Propagator object used for batch estimation
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
RelativeTol
Object
valid Propagator object
set
None
N/A
script
Relative Weighted RMS convergence criteria tolerance
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
Real
Real > 0
set
0.0001
dimensionless
script
229
Reference Guide
BatchEstimatorInv
Field
Description
ReportFile
Specifies the name of estimation report file
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
ReportStyle
Specifies the type of estimation report. The Normal style excludes reporting of observation TAI, partials, and frequency information. For GMAT
version R2016A, for normal GMAT operation, only the Normal style is
an allowed choice.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
ResetBestRMSIfDiverging
On/Off
On or Off
set
On
N/A
script
Allows detailed output of the batch estimator to be shown in the message
window
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
230
true/false
true or false
set
false
N/A
script
Allows residuals plots to be shown
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
ShowProgress
String
Normal
set
Normal
N/A
script
If set true and the estimation process has diverged, then the Best RMS is
reset to the current RMS.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
ShowAllResiduals
String
string containing a valid file name
set
'BatchEstimatorInv' + instancename + '.data'
N/A
script
true/false
true or false
set
true
N/A
script
BatchEstimatorInv
Field
Reference Guide
Description
UseInitialCovariance If set true, a priori error covariance term is added to the estimation cost
function.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
true/false
true or false
set
false
N/A
script
Remarks
Behavior of Convergence Criteria
GMAT has four input fields, RelativeTol, AbsoluteTol, MaximumIterations, and MaxConsecutiveDivergences that are used to determine if the estimator has converged after each new iteration.
Associated with these input fields are the two convergence tests shown below:
Absolute Weighted RMS convergence criteria
Weighted RMScurrent ≤ AbsoluteTol
Relative Weighted Root Mean Square (RMS) convergence criteria
|RMSP – RMSB|/ RMSB ≤ RelativeTol
where
RMSB = smallest Weighted RMS achieved during the current and previous iterations
RMSP = predicted Weighted RMS of next iteration
Batch estimation is considered to have converged when either or both of the above criteria is met
within MaximumIterations iterations or less.
Batch estimation is considered to have diverged when number of consecutive diverging iterations is
equal to or greater than MaxConsecutiveDivergences or the number of iterations exceeds MaximumIterations.
Behavior of Outer Loop Sigma Editing (OLSE)
GMAT has three input fields, OLSEMultiplicativeConstant, OLSEAdditiveConstant, and
OLSEInitialRMSSigma, that are used to 'edit' (i.e., reject or throw away) bad measurement data.
There are plans to have both an inner loop and and outer loop iteration editing procedure. Currently,
only the outer loop iteration editing procedure is implemented. This editing procedure is done on a
per iteration basis. Data that is edited is not used to calculate the state vector estimate for the current
iteration but the data is available as a candidate measurement for subsequent iterations. On the first
outer loop iteration, data is edited if
|Weighted Measurement Residual| > OLSEInitialRMSSigma
231
Reference Guide
BatchEstimatorInv
where the Weighted Measurement Residual for a single given measurement is given by
(O-C)/NoiseSigma
and where NoiseSigma is the input noise (one sigma) for the measurement type associated with
the given measurement. On subsequent outer loop iterations, data is edited if
|Weighted Measurement Residual| > OLSEMultiplicativeConstant * WRMSP + OLSEAdditiveConstant
where WRMSP is the predicted weighted RMS calculated at the end of the previous iteration.
Propagator Settings
The BatchEstimatorInv resource has a Propagator field containing the name of the Propagator
resource that will be used during the estimation process. It is recommended that if the ForceModel
resource associated with your propagator is using relative step control, i.e., ErrorControl =
RSSStep, then the minimum step size, MinStep, of your propagator should be set to 0.
Interactions
Resource
Description
Tracking- Must be created in order to tell the BatchEstimatorInv resource which data will be
FileSet re- processed
source
Propagator Used by GMAT to generate the predicted orbit
resource
RunEstiMust use the RunEstimator command to actually process the data defined by the
mator com- BatchEstimatorInv resource
mand
Examples
Below is an example of a configured batch estimator instance. In this example, estData is an instance
of a TrackingFileSet and ODProp is an instance of Propagator.
Create BatchEstimatorInv bat;
bat.ShowProgress
bat.Measurements
bat.AbsoluteTol
bat.RelativeTol
bat.MaximumIterations
bat.MaxConsecutiveDivergences
bat.Propagator
bat.ShowAllResiduals
bat.OLSEInitialRMSSigma
bat.OLSEMultiplicativeConstant
bat.OLSEAdditiveConstant
232
=
=
=
=
=
=
=
=
=
=
=
true;
{estData}
0.000001;
0.001;
10;
3;
ODProp;
On;
3000;
3;
0;
BatchEstimatorInv
bat.InversionAlgorithm
bat.EstimationEpochFormat
bat.EstimationEpoch
bat.ReportStyle
bat.ReportFile
Reference Guide
=
=
=
=
=
'Internal';
'FromParticipants';
'FromParticipants';
'Normal';
'BatchEstimator_Report.txt';
BeginMissionSequence;
For a comprehensive example of reading in measurements and running the estimator, see the Orbit
Estimation using DSN Range and Doppler Data tutorial.
233
234
Reference Guide
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, Color
Fields
Field
Description
3DModelFile
Allows you to load 3D models for your celestial body. Models must
be in .3ds model formats.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
3DModelOffsetX
This field lets you translate a celestial body in +X or -X axis of central
body's coordinate system.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
3DModelOffsetY
String
. 3ds model formats only
set
empty
N/A
GUI, script
Real
-3.5 <= Real <= 3.5
set
0.000000
N/A
GUI, script
This field lets you translate a celestial body in +Y or -Y axis of central
body's coordinate system.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
Real
-3.5 <= Real <= 3.5
set
0.000000
N/A
GUI, script
235
Reference Guide
CelestialBody
Field
Description
3DModelOffsetZ
This field lets you translate a celestial body in +Z or -Z axis of central
body's coordinate system.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
3DModelRotationX
Allows you to perform a fixed rotation of a celestial body's attitude
w.r.t X-axis of central body's coordinate system.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
3DModelRotationY
Real
-180 <= Real <= 180
set
0.000000
Deg.
GUI, script
Allows you to apply a scale factor to the celestial body's model size.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
236
Real
-180 <= Real <= 180
set
0.000000
Deg.
GUI, script
Allows you to perform a fixed rotation of a celestial body's attitude
w.r.t Z-axis of central body's coordinate system.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
3DModelScale
Real
-180 <= Real <= 180
set
0.000000
Deg.
GUI, script
Allows you to perform a fixed rotation of a celestial body's attitude
w.r.t Y-axis of central body's coordinate system.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
3DModelRotationZ
Real
-3.5 <= Real <= 3.5
set
0.000000
N/A
GUI, script
Real
0.001 <= Real <= 1000
set
10
N/A
GUI, script
CelestialBody
Reference Guide
Field
Description
CentralBody
The central body of the celestial body. The central body field is used
primarily by the GUI.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
EquatorialRadius
The body's equatorial radius.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
EopFileName
Real
Real > 0
set
6378.1363
km
GUI, script
Optional Earth EOP file to use instead of the EOP file defined in
the startup file. Note that an emtpy string is the default, and when set
to an empty string, the EOP file defined in the GMAT startup file is
used. This field is only valid for Earth .
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
FileName
String
Comet, Planet, Asteroid, or Moon
set
For Comet, Planet, Asteroid, the default is
Sun. For Moon, the default is Earth.
N/A
GUI, script
Filename
Valid file name
set
''
N/A
script
Path and/or name of texture map file used in OrbitView graphics.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
String
A file of the following format:
.jpeg, .bmp, .png, .gif, .tif, .pcx, .pnm, .tga,
or .xpm
set
'../
data/graphics/texture/GenericCelestialBody.jpg'
N/A
GUI, script
237
Reference Guide
CelestialBody
Field
Description
Flattening
The body's polar flattening.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
Real
Real >= 0
set
0.0033527
N/A
GUI, script
FrameSpiceKernelName List of SPICE FK files to load for this body. Used to define celestial
body properties for use with ContactLocator and EclipseLocator.
See Remarks.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
Mu
The body's gravitational parameter.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
NAIFId
Integer
Integer
set
-123456789
N/A
GUI, script
The time interval between updates for Earth nutation matrix. If NutationUpdateInterval = 3600, then GMAT only updates nutation on
an hourly basis.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
238
Real
Real > 0
set
398600.4415
km^3/s^2
GUI, script
NAIF Integer ID for body.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
NutationUpdateInterval
String array
Paths to valid SPICE FK files
set
Varies for built-in bodies. Empty for userdefined bodies.
N/A
GUI, script
Real
Real >= 0
set
60
sec.
GUI, script
CelestialBody
Reference Guide
Field
Description
OrbitColor
Allows you to set available colors on built-in or user-defined
CelestialBody objects that are drawn on the 3D OrbitView
graphics displays. Colors on a CelestialBody object can be set
through a string or an integer array. For example: Setting a celestial body's orbit color to red can be done in the following two ways: CelestialBody.OrbitColor = Red or
Celestialbody.OrbitColor = [255 0 0]. This field can be
modified in the Mission Sequence as well.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
OrbitSpiceKernelName
List of SPK kernels. Providing emtpy brackets unloads previously
loaded kernels.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
OrientationEpoch
Integer Array or String
Any color available from the Orbit Color
Picker in GUI. Valid predefined color name
or RGB triplet value between 0 and 255.
set
Orchid for user-defined Planet, Pink for
user-defined Comet, Salmon for user-defined Asteroid and Tan for user-defined
Moon
N/A
GUI, script
Reference array
valid array of SPK kernels
set
N/A
N/A
GUI, script
The reference epoch for orientation data.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
String
6116.0 <= Epoch <= 58127.5
set
21545.0
A1 Modified Julian Epoch
GUI, script
239
Reference Guide
CelestialBody
Field
Description
PlanetarySpiceKernelName
List of SPICE PCK files to load for this body. Used to define celestial
body properties for use with ContactLocator and EclipseLocator.
See Remarks.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
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 builtin bodies.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
RotationConstant
String
SPICE
set
DE405 for built-in bodies. SPICE for userdefined bodies.
N/A
GUI, script
The body's spin angle at the orientation epoch.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
240
String array
Paths to valid SPICE PCK files
set
Varies for built-in bodies. Empty for userdefined bodies.
N/A
GUI, script
Real
Real
set
190.147
deg
GUI, script
CelestialBody
Reference Guide
Field
Description
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
Allowed Values
Access
Default Value
Units
Interfaces
RotationRate
The body's spin rate.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
SpiceFrameId
Real
Real
set
360.9856235
deg/day
GUI, script
SPICE ID of body-fixed frame. Used to define celestial body properties for use with ContactLocator and EclipseLocator. See Remarks.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
SpinAxisDECConstant
String
IAUSimplified, DE405, FK5IAU1980,
IAU2000. See discussion below for more details as not all options are allowed for all bodies.
set
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.
N/A
GUI, script
String
Valid SPICE frame ID (text or numeric)
set
Varies for built-in bodies. Empty for userdefined bodies.
N/A
GUI, script
The declination of the body's spin axis at the orientation epoch.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
Real
Real
set
90
deg
GUI, script
241
Reference Guide
CelestialBody
Field
Description
SpinAxisDECRate
The rate of change of the body's spin axis declination.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
SpinAxisRAConstant
The right ascension of the body's spin axis at the orientation epoch.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
SpinAxisRARate
Real
Real
set
-0.641
deg/century
GUI, script
Allows you to set available colors on CelestialBody object's perturbing orbital trajectories that are drawn during iterative processes such
as Differential Correction or Optimization. The target color can be
identified through a string or an integer array. For example: Setting a
celestial body's perturbing trajectory color to yellow can be done in
following two ways: Celestialbody.TargetColor = Yellow
or Celestialbody.TargetColor = [255 255 0] . This field
can be modified in the Mission Sequence as well.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
242
Real
Real
set
-0.641
deg
GUI, script
The rate of change of the body's right ascension.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
TargetColor
Real
Real
set
-0.5570
deg/century
GUI, script
Integer Array or String
Any color available from the Orbit Color
Picker in GUI. Valid predefined color name
or RGB triplet value between 0 and 255.
set
Dark Gray for built-in or user-defined Planet, Comet, Asteroid and Moon
N/A
GUI, script
CelestialBody
Reference Guide
Field
Description
TextureMapFileName
Allows you to load a texture map file for your celestial body.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
String
texture map files in jpeg format
set
'GenericCelestialBody.jpg'
N/A
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.
243
Reference Guide
CelestialBody
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.
244
CelestialBody
Reference Guide
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.
245
Reference Guide
CelestialBody
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.
246
CelestialBody
Reference Guide
The CelestialBody Visualization tab is shown below for creating a custom CelestialBody. On
the visualization tab, you can set data such as 3d model of a celestial body, texture file, translation
and rotation of a celestial body on all three axes, scale of the 3D model as well as assign orbit and
target colors to the orbit of the body.
247
Reference Guide
CelestialBody
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 SpinAxisRACon248
CelestialBody
Reference Guide
stant, 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.
Setting colors on orbits of celestial bodies
GMAT allows you to assign colors to orbits of celestial bodies that are drawn in the OrbitView
graphics display windows. GMAT also allows you to assign colors to perturbing celestial body orbital
trajectories drawn during iterative processes such as differential correction or optimization. The
CelestialBody object's OrbitColor and TargetColor fields are used to assign colors to both orbital
249
Reference Guide
CelestialBody
and perturbing trajectories. See the Fields section for description of these two fields. Also see Color
documentation for discussion and examples on how to set colors on a celestial body.
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
NAIF 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.
Configuring for event location
GMAT's event location subsystem (consisting of ContactLocator and EclipseLocator) uses celestial body definitions from the SPICE toolkit. Properites such as radius, flattening, ephemeris, and
orientation must be configured separately for use with the event locators.
250
CelestialBody
Reference Guide
CelestialBody shape and orientation are configured via SPICE PCK files, loaded from two sources
in the following order:
1. SolarSystem.PCKFilename
2. Sun.PlanetarySpiceKernelName (in list order), followed by Mercury, Venus, Earth, Mars,
Jupiter, Saturn, Uranus, Neptune, Pluto, Luna
3. User-defined bodies
Data loaded last takes precedence over data loaded first, if there is a conflict. Note that because
the SPICE kernel pool is shared for the entire run, a PCK file loaded for Pluto may override data
loaded by Sun, if the file contains conflicting data. Note that this order isn't absolute—coordinate
systems that with an SPK-defined origin load differently, for example. To determine the exact load
order, see the GmatLog.txt file.
Note
GMAT's SPICE kernel load order is based on many factors, and can be unpredictable.
Therefore, it is important that the kernels referenced by a mission be consistent. For
example, NAIF's de421.bsp and mar085.bsp are consistent, because they are both
based on the DE421 model. Inconsistent kernels can cause unpredictable behavior
based on the order in which they are loaded.
The body-fixed frame for a CelestialBody is defined on the Orientation tab by the SpiceFrameId
and SpiceFrameKernelFile fields. The SpiceFrameId contains the SPICE ID for the body-fixed
frame, which may be built-in or defined via external FK files. External FK files can be loaded by
adding them to the SpiceFrameKernelFile list for each body. These files are loaded just after PlanetarySpiceKernelName for each body. The list of built-in frames is available as an appendix in the
SPICE documentation. GMAT's default frames are:
• Earth: ITRF93
• Luna: MOON_PA
• Other default bodies: IAU_CelestialBody
The Earth ITRF93 frame is defined by three high-fidelity orientation PCK files, shown below. More
information on these files can be found in the NAIF aareadme.txt file.
• earth_start_end_predict.bpc: long-term low-fidelity EOP predictions
• earth_start_end.bpc: long-term low-fidelity historical EOP
• earth_start_end_filedate.bpc: near-term high-fidelity EOP history and predictions
The Luna MOON_PA frame is defined by an orientation PCK file and a frame-defining FK file,
shown below. More information can be found in the NAIF PCK aareadme.txt file and the FK
aareadme.txt file. Other versions of the MOON_PA frame are available from NAIF.
• moon_pa_de421_1900-2050.bpc: Moon orientation consistent with DE421 PA frame
• moon_080317.tf: MOON_PA frame definition
251
Reference Guide
CelestialBody
Examples
Configure a CelestialBody to model Saturn's moon Titan. Note you must obtain the SPICE kernel
named "sat288.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/sat288.bsp' ...
}
Titan.SpiceFrameId
= 'IAU_TITAN'
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
252
Reference Guide
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
Field
Description
AlignmentVectorX
The x component of the AlignmentVector expressed in the local frame (for example, expressed in the LocalAlignedConstrained frame). Used for the following axis
systems: LocalAlignedConstrained.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
Real
-∞ < Real < ∞ (norm of AlignmentVector >= 1e-9)
set
1
N/A
gui,script
AlignThe y component of the AlignmentVector expressed in the local frame (for exammentVecto- ple, expressed in the LocalAlignedConstrained frame). Used for the following axis
rY
systems: LocalAlignedConstrained.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
AlignmentVectorZ
Real
-∞ < Real < ∞ (norm of AlignmentVector>= 1e-9)
set
0
N/A
gui, script
The z component of the AlignmentVector expressed in the local frame (for example, expressed in the LocalAlignedConstrained frame). Used for the following axis
systems: LocalAlignedConstrained.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
Real
-∞ < Real < ∞ (norm of AlignmentVector>= 1e-9)
set
0
N/A
gui,script
253
Reference Guide
CoordinateSystem
Field
Description
Axes
The axes of the CoordinateSystem.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
String
MJ2000Eq, MJ2000Ec, ICRF, ITRF, MODEq, MODEc, TODEq, TODEc, MOEEq, MOEEc, TOEEq,
TOEEc, ObjectReferenced, Equator, BodyFixed,
BodyInertial, GSE, GSM, Topocentric, BodySpinSun
set
MJ2000Eq
N/A
GUI, script
ConThe x component of the ConstraintVector expressed in the local frame (for examstraintVec- ple, expressed in the LocalAlignedConstrained frame). Used for the following axis
torX
systems: LocalAlignedConstrained.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
Real
-∞ < Real < ∞ (norm of ConstraintVector>= 1e-9)
set
0
N/A
gui,script
ConThe y component of the ConstraintVector expressed in the local frame (for examstraintVec- ple, expressed in the LocalAlignedConstrained frame). Used for the following axis
torY
systems: LocalAlignedConstrained.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
Real
-∞ < Real < ∞ (norm of ConstraintVector>= 1e-9)
set
0
N/A
gui,script
ConThe z component of the ConstraintVector expressed in the local frame (for examstraintVec- ple, expressed in the LocalAlignedConstrained frame). Used for the following axis
torZ
systems: LocalAlignedConstrained.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
254
Real
-∞ < Real < ∞ (norm of ConstraintVector>= 1e-9)
set
1
N/A
gui,script
CoordinateSystem
Field
Reference Guide
Description
Constrain- The x component of the ConstraintReferenceVector expressed in the ContReferstraintCoordinateSystem. Used for the following axis systems: LocalAlignedConenceVecstrained.
torX
Data Type
Real
Allowed Values
-∞ < Real < ∞ (norm of ConstraintReferenceVector>=
1e-9)
Access
set
Default Value
0
Units
N/A
Interfaces
gui,script
Constrain- The y component of the ConstraintReferenceVector expressed in the ContReferstraintCoordinateSystem. Used for the following axis systems: LocalAlignedConenceVecto- strained.
rY
Data Type
Real
Allowed Values
-∞ < Real < ∞ (norm of ConstraintReferenceVector>=
1e-9)
Access
set
Default Value
0
Units
N/A
Interfaces
gui,script
Constrain- The z component of the ConstraintReferenceVector expressed in the ContReferstraintCoordinateSystem. Used for the following axis systems: LocalAlignedConenceVecstrained.
torZ
Data Type
Real
Allowed Values
-∞ < Real < ∞ (norm of ConstraintReferenceVector>=
1e-9)
Access
set
Default Value
1
Units
N/A
Interfaces
gui,script
Constraint The coordinate system for the ConstraintReferenceVector. Used for the following
Coordinate axis sytems: LocalAlignedConstrained.
System
Data Type
Resource
Allowed Values
CoordinateSystem
Access
set
Default Value
EarthMJ2000Eq
Units
N/A
Interfaces
gui,script
255
Reference Guide
CoordinateSystem
Field
Description
Epoch
The reference epoch for the CoordinateSystem. This field is only used for TOE
amd MOE axis types.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
Origin
The origin of the CoordinateSystem.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
Primary
String
A1 Modified Julian epoch.
set
21545
Modified Julian Date
GUI, script
String
CelestialBody, Spacecraft, LibrationPoint, Barycenter,
SolarSystemBarycenter, GroundStation
set
Earth
N/A
GUI, script
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
Allowed Values
Access
Default Value
Units
Interfaces
String
CelestialBody, Spacecraft, LibrationPoint, Barycenter,
SolarSystemBarycenter, GroundStation
set
Earth
N/A
GUI, script
ReferThe reference object for a LocalAlignedConstrained axis system. The axes are comenceObject puted such that the AlignmentVector in the body frame is aligned with the vector
pointing from the Origin to the ReferenceObject.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
256
Resource
A Resource that has coordinates. For example: CelestialBody, Spacecraft, LibrationPoint, Barycenter, SolarSystemBarycenter, GroundStation.
set
Luna
N/A
gui,script
CoordinateSystem
Field
Reference Guide
Description
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
Allowed Values
Access
Default Value
Units
Interfaces
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
Allowed Values
Access
Default Value
Units
Interfaces
YAxis
String
R,V, N, -R, -V, -N, or empty
set
R
N/A
GUI, script
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
Allowed Values
Access
Default Value
Units
Interfaces
Zaxis
String
CelestialBody, Spacecraft, LibrationPoint, Barycenter,
SolarSystemBarycenter, GroundStation
set
Luna
N/A
GUI, script
String
R,V, N, -R, -V,-N, or empty
set
No Default
N/A
GUI, script
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
Allowed Values
Access
Default Value
Units
Interfaces
String
R,V, N, -R, -V,-N, or empty
set
N
N/A
GUI, script
257
Reference Guide
CoordinateSystem
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.
258
CoordinateSystem
Reference Guide
When editing an existing CoordinateSystem, you use the CoordinateSystem dialog box. The default configuration is shown above.
259
Reference Guide
CoordinateSystem
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.
260
CoordinateSystem
Reference Guide
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.
261
Reference Guide
CoordinateSystem
If you select LocalAlignedConstrained as the axes Type, then CoordinateSystem dialog displays
the fields illustrated above for configuring the axes.
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.
262
CoordinateSystem
Reference Guide
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).
263
Reference Guide
CoordinateSystem
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}.
264
CoordinateSystem
Reference Guide
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 nonorthogonal 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
Name
Origin Axes
Description
EarthMJ2000Eq Earth
MJ2000Eq An Earth equator inertial system based on IAU-1976/
FK5 theory with 1980 update to nutation.
EarthMJ2000Ec Earth
MJ2000Ec
EarthFixed
Earth
BodyFixed An Earth fixed system based on IAU-1976/FK5 theory
with 1980 update to nutation.
EarthICRF
Earth
ICRF
An Earth ecliptic inertial system based on IAU-1976/
FK5 theory with 1980 update to nutation.
An Earth equator inertial system based on IAU-2000 theory with 2006 update to precession.
265
Reference Guide
CoordinateSystem
Description of Axes Types
266
Axes Name
Origin Base Type Description
Limitations
MJ2000Eq
None
IAU-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.
MJ2000Ec
None
IAU-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 ecliptic 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.
ICRF
None
IAU-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.
LocalAlignedConstrained
None
IAU-1976
FK5
The LocalAlignedConstrained axis system is an aligned
constrained system based on the position of the ReferenceObject with respect to the Origin and is computed using the well known Triad algorithm. The axes
are computed such that the AlignmentVector, defined
as the components of the alignment vector expressed in
the LocalAlignedConstrained system, is aligned with
the position of the ReferenceBody w/r/t the origin.
The rotation about the AlignmentVector is resolved
by minimizing the angle between the ContraintVector,
defined as the constraint vector expressed in the LocalAlignedConstrained system, and the ConstraintReferenceVector, defined as the constraint reference vector expressed in the ConstraintCoordinateSystem. The
alignment vectors and the constraint vectors cannot have
zero length. Similarly, the cross products of the constraint
vector and alignment vector cannot have zero length.
CoordinateSystem
Reference Guide
Axes Name
Origin Base Type Description
Limitations
MODEq
None
IAU-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.
MODEc
None
IAU-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.
TODEq
None
IAU-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.
TODEc
None
IAU-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.
MOEEq
None
IAU-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.
MOEEc
None
IAU-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.
TOEEq
None
IAU-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.
267
Reference Guide
CoordinateSystem
Axes Name
Origin Base Type Description
Limitations
TOEEc
None
IAU-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.
ObjectReferenced
None
IAU-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.
Equator
Celestial
Body
IAU-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”.
BodyFixed
Celes- IAU-1976
tial
FK5
Body or
Spacecraft
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”.
When Origin is a Spacecraft, the axes are computed using the Spacecraft’s attitude model. Note: not all attitude
models compute body rates. In the case that body rates
are not available on a spacecraft, a request for velocity
transformations using a BodyFixed axis system will result in an error.
268
CoordinateSystem
Reference Guide
Axes Name
Origin Base Type Description
Limitations
BodyInertial
Celestial
Body
IAU-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”
GSE
None
IAU-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.
GSM
None
IAU-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.
Topocentric
Earth
IAU-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.
BodySpinSun
Celestial
Body
IAU-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.
269
Reference Guide
CoordinateSystem
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
270
CoordinateSystem
Reference Guide
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
=
anOrbitView.CoordinateSystem
=
anOrbitView.ViewPointReference
=
anOrbitView.ViewPointVector
=
anOrbitView.ViewDirection
=
anOrbitView.ViewUpCoordinateSystem
anOrbitView.Axes
=
anOrbitView.XYPlane
=
{aSpacecraft, Earth, Sun, Luna}
RotatingSEML1Coord
SunEarthMoonL1
[-1500000 0 0 ]
SunEarthMoonL1
= RotatingSEML1Coord
Off
Off
BeginMissionSequence
Propagate aPropagator(aSpacecraft, {aSpacecraft.ElapsedDays = 180})
271
272
Reference Guide
ContactLocator
A line-of-sight event locator between a target Spacecraft and an observer GroundStation
Description
Note
ContactLocator is a SPICE-based subsystem that uses a parallel configuration for the
solar system and celestial bodies from other GMAT components. For precision applications, care must be taken to ensure that both configurations are consistent. See Remarks for details.
A ContactLocator is an event locator used to find line-of-sight contact events between a Spacecraft and a GroundStation. By default, a ContactLocator generates a text event report listing the
beginning and ending times of each line-of-sight event, along with the duration. Contact location can
be performed over the entire propagation interval or over a subinterval, and can optionally adjust
for light-time delay and stellar aberration. Contact location can be configured to search for times
of occultation of other CelestialBody resources that may block line of sight, and can limit contact
events to a specified minimum elevation angle configured on the GroundStation.
Contact location can be performed between one Spacecraft (Target) and any number of GroundStation resources (Observers). Each target-observer pair is searched individually, and results in a
separate segment of the resulting report. All pairs must use the same interval and search options; to
customize the options per pair, use multiple ContactLocator resources.
Third-body occultation searches can be included by listing one or more CelestialBody resources
in the OccultingBodies list. Any configured CelestialBody can be used as an occulting body,
including user-defined ones. By default, no occultation searches are performed; the central body of
the GroundStation is included automatically in the basic line-of-sight algorithm.
By default, the ContactLocator searches the entire interval of propagation of the Target, after applying certain endpoint light-time adjustments; see Remarks for details. To search a custom interval,
set UseEntireInterval to False and set InitialEpoch and FinalEpoch accordingly. Note that
these epochs are assumed to be at the observer, and so must be valid when translated to the target
via light-time delay and stellar aberration, if configured. If they fall outside the propagation interval
of the Target, GMAT will display an error.
The contact locator can optionally adjust for both light-time delay and stellar aberration, using either a transmit sense (Observer→Target) or receive sense (Observer←Target) depending on the
value of LightTimeDirection. The light-time direction affects the valid search interval by limiting
searches near the start of the interval (for transmit sense) or the end of the interval (for receive
sense). See Remarks for details. Stellar aberration is only applied for the line-of-sight portion of the
search; it has no effect during occultation searches.
The event search is performed at a fixed step through the interval. You can control the step size (in
seconds) by setting the StepSize field. An appropriate choice for step size is no greater than half the
period of the line-of-sight function—that is, half the orbit period for an elliptical orbit. If third-body
273
Reference Guide
ContactLocator
occultations are used, the maximum step size is no greater than the minimum-duration occultation
event you wish to find. See Remarks for details.
GMAT uses the SPICE library for the fundamental event location algorithm. As such, all celestial
body data is loaded from SPICE kernels for this subsystem, rather than GMAT's own CelestialBody
shape and orientation configuration. See Remarks for details.
Unless otherwise mentioned, ContactLocator fields cannot be set in the mission sequence.
See Also: CelestialBody, GroundStation, Spacecraft, EclipseLocator, FindEvents
Fields
Field
Description
Filename
Name and path of the contact report file. This field can be set in the mission sequence.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
FinalEpoch
InitialEpoch
274
String
Valid file path
set
'ContactLocator.txt'
N/A
GUI, script
Last epoch to search for contacts, in the format specified by InputEpochFormat. The epoch is relative to the Observer, and must map
to a valid epoch in the Target ephemeris interval, including any light time.
This field can be set in the mission sequence.
Data Type
Allowed Values
Access
Default Value
Units
String
Valid epoch in available spacecraft ephemeris
set
'21545.138'
ModifiedJulian epoch formats: days
Interfaces
Gregorian epoch formats: N/A
GUI, script
First epoch to search for contacts, in the format specified by InputEpochFormat. The epoch is relative to the Observer, and must map
to a valid epoch in the Target ephemeris interval, including any light time.
This field can be set in the mission sequence.
Data Type
Allowed Values
Access
Default Value
Units
String
Valid epoch in available spacecraft ephemeris
set
'21545'
ModifiedJulian epoch formats: days
Interfaces
Gregorian epoch formats: N/A
GUI, script
ContactLocator
Field
Reference Guide
Description
LightTimeDirection Sense of light-time calculation: transmit from observer or receive at observer. The clock is always hosted on the Target.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
Observers
List of the contact observer objects. Can be any number of GMAT
GroundStation resources.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
OccultingBodies
List of GroundStation resources
Any existing GroundStation resources
set
Empty list
N/A
GUI, script
List of occulting bodies to search for contacts. Can be any number of
GMAT CelestialBody-type resources, such as Planet, Moon, Asteroid,
etc. Note that an occulting body must have a mass (e.g. not LibrationPoint
or Barycenter).
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
RunMode
Enumeration
Transmit, Receive
set
Transmit
N/A
GUI, script
List of CelestialBody resources (e.g. Planet, Asteroid, Moon, etc.)
Any existing CelestialBody-class resources
set
Empty list
N/A
GUI, script
Mode of event location execution. 'Automatic' triggers event location
to occur automatically at the end of the run. 'Manual' limits execution
only to the FindEvents command. 'Disabled' turns of event location
entirely.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
Enumeration
Automatic, Manual, Disabled
set
'Automatic'
N/A
GUI, script
275
Reference Guide
ContactLocator
Field
Description
StepSize
Step size of event locator. See Remarks for discussion of appropriate values.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
Target
The target Spacecraft resource to search for contacts.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
UseEntireInterval
Real
StepSize > 0
set
10
s
GUI, script
Spacecraft resource
Any existing Spacecraft resource
set
First configured Spacecraft resource
N/A
GUI, script
Search the entire available Target ephemeris interval, after adjusting the
end-points for light-time delay as appropriate. See Remarks for details. This
field can be set in the mission sequence.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
Boolean
true, false
set
true
N/A
GUI, script
UseLightTimeDelay Use light-time delay in the event-finding algorithm. The clock is always
hosted on the Observer.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
Boolean
true, false
set
true
N/A
GUI, script
UseStellarAberration Use stellar aberration in addition to light-time delay in the event-finding
algorithm. Light-time delay must be enabled. Stellar aberration only affects
line-of-sight searches, not occultation searches.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
276
Boolean
true, false
set
true
N/A
GUI, script
ContactLocator
Reference Guide
Field
Description
WriteReport
Write an event report when event location is executed. This field can be
set in the mission sequence.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
Boolean
true, false
set
true
N/A
GUI, script
GUI
The default ContactLocator GUI for a new resource is shown above. You can choose one Spacecraft from Target, which is populated by all the Spacecraft resources currently configured in the
mission. In the Observers list, you can check the box next to all GroundStations you want to
search for contacts to.
To search for third-body occultations, check the boxes next to any applicable CelestialBody resources in the Occulting Bodies list. This list shows all celestial bodies currently configured in the
mission. Note that each occultation search will increase the execution time of the overall search.
You can configure the output via Filename, Run Mode, and Write Report near the bottom. If
Write Report is enabled, a text report will be written to the file specified in Filename. The search
will execute during FindEvents commands (for Manual or Automatic modes) and automatically
at the end of the mission (for Automatic mode), depending on the Run Mode.
277
Reference Guide
ContactLocator
You can configure the search interval via the options in the upper right. Uncheck Use Entire Interval to set the search interval manually. See the Remarks section for considerations when setting
the search interval.
You can control the search algorithm via the options in the bottom right. Configure light-time and
stellar aberration via the check boxes next to each, and select the signal direction via the Light-time
direction selection.
To control the fidelity and execution time of the search, set the Step size appropriately. See the
Remarks section for details.
Remarks
Data configuration
The ContactLocator implementation is based on the NAIF SPICE toolkit, which uses a different mechanism for environmental data such as celestial body shape and orientation, planetary
ephemerides, body-specific frame definitions, and leap seconds. Therefore, it is necessary to maintain two parallel configurations to ensure that the event location results are consistent with GMAT's
own propagation and other parameters. The specific data to be maintained is:
• Planetary shape and orientation:
• GMAT core: CelestialBody.EquatorialRadius, Flattening, SpinAxisRAConstant,
SpinAxisRARate, etc.
• ContactLocator: SolarSystem.PCKFilename, CelestialBody.PlanetarySpiceKernelName
• Planetary ephemeris:
• GMAT
core:
SolarSystem.DEFilename,
or
(SolarSystem.SPKFilename,
CelestialBody.OrbitSpiceKernelName, CelestialBody.NAIFId)
• ContactLocator: SolarSystem.SPKFilename, CelestialBody.OrbitSpiceKernelName,
CelestialBody.NAIFId
• Body-fixed frame:
• GMAT core: built-in
• ContactLocator: CelestialBody.SpiceFrameId, CelestialBody.FrameSpiceKernelName
• Leap seconds:
• GMAT core: startup file LEAP_SECS_FILE setting
• ContactLocator: SolarSystem.LSKFilename
Note
For precise applications, the Earth shape must be consistent in both subsystems to
ensure consistent placement of a GroundStation. The following script lines make the
two definitions consistent.
SolarSystem.PCKFilename = '..\data\planetary_coeff\pck00010.tpc'
Earth.EquatorialRadius = 6378.1366
Earth.Flattening = 0.00335281310845547
See SolarSystem and CelestialBody for more details.
278
ContactLocator
Reference Guide
Search interval
The ContactLocator search interval can be specified either as the entire ephemeris interval of the
Target, or as a user-defined interval. Each mode offers specific behavior related to handling of lighttime delay and discontinuous intervals.
If UseEntireInterval is true, the search is performed over the entire ephemeris interval of the
Target, including any gaps or discontinuities. If light-time delay is enabled, the search interval is
truncated by the approximate light time to allow SPICE to determine the exact light-time delay
between the participants during the search. If LightTimeDirection is Transmit, the beginning of
the interval is truncated. If LightTimeDirection is Receive, the end of the interval is truncated.
In either case, the other end of the interval is trimmed slightly via bisection to avoid stepping beyond
the end of the ephemeris due to numeric precision issues. This trimming is typically less than 1 s. The
endpoints of gaps or discontinuities are not modified, so these are not fully supported if light-time
delay is enabled. If light-time delay is disabled, the entire interval is used directly, with no endpoint
manipulation.
If UseEntireInterval is false, the provided InitialEpoch and FinalEpoch are used to form the
search interval directly. This interval is consistent with the Observer clock, and does not support
the inclusion of gaps or discontinuities from the Target ephemeris. The user must ensure than the
provided interval results in valid Target ephemeris epochs after light-time delay and stellar aberration
have been applied.
These rules are summarized in the following table, where t0 and tf are the beginning and end of the
Target ephemeris, respectively, and lt is the light time between the Target and the Observer.
UseLightTimeDelay
true
UseEntireInterval true
UseEntireInterval false
Effective interval
LightTimeDirection =
'Transmit': [t0+lt, tf]
Effective interval
[InitialEpoch, FinalEpoch]
Discontinuous intervals
Unsupported. Behavior is undefined.
LightTimeDirection =
'Receive': [t0, tf-lt]
Discontinuous intervals
Unsupported. Behavior is undefined.
UseLightTimeDelay
false
Effective interval
[t0, tf]
Discontinuous intervals
Fully supported
Effective interval
[InitialEpoch, FinalEpoch]
Discontinuous intervals
Fully supported
Run modes
The ContactLocator works in conjunction with the FindEvents command: the ContactLocator resource defines the configuration of the event search, and the FindEvents command executes the search at a specific point in the mission sequence. The mode of interaction is defined by
ContactLocator.RunMode, which has three options:
• Automatic: All FindEvents commands are executed as-is, plus an additional FindEvents is
executed automatically at the end of the mission sequence.
279
Reference Guide
ContactLocator
• Manual: All FindEvents commands are executed as-is.
• Disabled: FindEvents commands are ignored.
Search algorithm
The ContactLocator uses the NAIF SPICE GF (geometry finder) subsystem to perform event
location. Specifically, the following two calls are used for the search:
• gfposc_c: For line-of-sight search above the GroundStation.MinimumElevationAngle
• gfoclt_c: For third-body occultation searches
Both functions implement a fixed-step search method through the interval, with an embedded rootlocation step if an event is found. Proper selection of StepSize differs between the two functions.
For the basic line-of-sight search, without third-body occultations, StepSize can be set as high as
one-half the period of the event function. For an elliptic orbit, this is up to one-half the orbit period.
For third-body occultations, StepSize should be set equal to the length of the minimum-duration
event to be found, or equal to the lenght of the minimum-duration gap between events, whichever
is smaller. To guarantee location of 10-second occultations, set StepSize = 10.
If no third-body occultations are to be found, you can increase performance of the search by increasing StepSize per the notes above.
For details, see the reference documentation for the two functions linked above.
Report format
When WriteReport is enabled, ContactLocator outputs an event report at the end of each search
execution. The report contains the following data:
• Target name
• For each Observer:
• Observer name
• For each event:
• Event start time (UTC)
• Event stop time (UTC)
• Duration (s)
• Total number of events
A sample report is shown below.
Target: DefaultSC
Observer: GroundStation1
Start Time (UTC)
01 Jan 2000 13:18:45.268
01 Jan 2000 15:06:44.752
Number of events : 2
280
Stop Time (UTC)
01 Jan 2000 13:29:54.824
01 Jan 2000 15:18:22.762
Duration (s)
669.55576907
698.01023654
ContactLocator
Observer: GroundStation2
Start Time (UTC)
01 Jan 2000 13:36:13.792
Reference Guide
Stop Time (UTC)
01 Jan 2000 13:47:51.717
Duration (s)
697.92488540
Number of events : 1
Event location with SPK propagator
When using the SPK propagator, you load one or more SPK ephemeris files using the
Spacecraft.OrbitSpiceKernelName field. For the purposes of event location, this field causes the
appropriate ephemeris files to be loaded automatically on run, and so use of the Propagate command is not necessary. This is an easy way of performing event location on an existing SPK ephemeris
file. See the example below.
Examples
Perform a basic contact search in LEO:
SolarSystem.EphemerisSource = 'DE421'
Earth.EquatorialRadius = 6378.1366
Earth.Flattening = 0.00335281310845547
Create Spacecraft sat
sat.DateFormat = UTCGregorian
sat.Epoch = '15 Sep 2010 16:00:00.000'
sat.CoordinateSystem = EarthMJ2000Eq
sat.DisplayStateType = Keplerian
sat.SMA = 6678.14
sat.ECC = 0.001
sat.INC = 0
sat.RAAN = 0
sat.AOP = 0
sat.TA = 180
Create ForceModel fm
fm.CentralBody = Earth
fm.PrimaryBodies = {Earth}
fm.GravityField.Earth.PotentialFile = 'JGM2.cof'
fm.GravityField.Earth.Degree = 0
fm.GravityField.Earth.Order = 0
fm.GravityField.Earth.EarthTideModel = 'None'
fm.Drag.AtmosphereModel = None
fm.PointMasses = {}
fm.RelativisticCorrection = Off
fm.SRP = Off
281
Reference Guide
ContactLocator
Create Propagator prop
prop.FM = fm
prop.Type = RungeKutta89
Create GroundStation GS
GS.CentralBody = Earth
GS.StateType = Spherical
GS.HorizonReference = Ellipsoid
GS.Location1 = 0;
GS.Location2 = 0;
GS.Location3 = 0;
Create ContactLocator cl
cl.Target = sat
cl.Observers = {GS}
cl.Filename = 'Simple.report'
BeginMissionSequence
Propagate prop(sat) {sat.ElapsedSecs = 10800}
Perform a contact event search from an Earth ground station to a Mars orbiter, with Phobos occultations:
% Mars orbiter, 2 days, Mars and Phobos eclipses
SolarSystem.EphemerisSource = 'SPICE'
SolarSystem.SPKFilename = 'de421.bsp'
Mars.OrbitSpiceKernelName = '../data/planetary_ephem/spk/mar063.bsp'
Earth.EquatorialRadius = 6378.1366
Earth.Flattening = 0.00335281310845547
Create Spacecraft sat
sat.DateFormat = UTCGregorian
sat.Epoch = '11 Mar 2004 12:00:00.000'
sat.CoordinateSystem = MarsMJ2000Eq
sat.DisplayStateType = Cartesian
sat.X = -1.436997966893255e+003
sat.Y = 2.336077717512823e+003
sat.Z = 2.477821416108639e+003
sat.VX = -2.978497667195258e+000
sat.VY = -1.638005864673213e+000
sat.VZ = -1.836385137438366e-001
Create ForceModel fm
fm.CentralBody = Mars
fm.PrimaryBodies = {Mars}
282
ContactLocator
Reference Guide
fm.GravityField.Mars.PotentialFile = 'Mars50c.cof'
fm.GravityField.Mars.Degree = 0
fm.GravityField.Mars.Order = 0
fm.Drag.AtmosphereModel = None
fm.PointMasses = {}
fm.RelativisticCorrection = Off
fm.SRP = Off
Create Propagator prop
prop.FM = fm
prop.Type = RungeKutta89
Create Moon Phobos
Phobos.CentralBody = 'Mars'
Phobos.PosVelSource = 'SPICE'
Phobos.NAIFId = 401
Phobos.OrbitSpiceKernelName = {'mar063.bsp'}
Phobos.SpiceFrameId = 'IAU_PHOBOS'
Phobos.EquatorialRadius = 13.5
Phobos.Flattening = 0.3185185185185186
Phobos.Mu = 7.093399e-004
Create Moon Deimos
Deimos.CentralBody = 'Mars'
Deimos.PosVelSource = 'SPICE'
Deimos.NAIFId = 402
Deimos.OrbitSpiceKernelName = {'mar063.bsp'}
Deimos.SpiceFrameId = 'IAU_DEIMOS'
Deimos.EquatorialRadius = 7.5
Deimos.Flattening = 0.30666666666666664
Deimos.Mu = 1.588174e-004
Create CoordinateSystem MarsMJ2000Eq
MarsMJ2000Eq.Origin = Mars
MarsMJ2000Eq.Axes = MJ2000Eq
Create GroundStation GS
GS.CentralBody = Earth
GS.StateType = Spherical
GS.HorizonReference = Ellipsoid
GS.Location1 = 36.3269
GS.Location2 = 127.433
GS.Location3 = 0.081
Create ContactLocator cl
cl.Target = sat
cl.Observers = {GS}
cl.OccultingBodies = {Sun, Mercury, Venus, Luna, Mars, Phobos, Deimos}
cl.Filename = 'Martian.report'
283
Reference Guide
ContactLocator
cl.StepSize = 5
BeginMissionSequence
Propagate prop(sat) {sat.ElapsedDays = 2}
Perform contact location on an existing SPK ephemeris file:
SolarSystem.EphemerisSource = 'DE421'
Earth.EquatorialRadius = 6378.1366
Earth.Flattening = 0.00335281310845547
Create Spacecraft sat
sat.OrbitSpiceKernelName = {'../data/vehicle/ephem/spk/Events_Simple.bsp'}
Create GroundStation GS
GS.CentralBody = Earth
GS.StateType = Spherical
GS.HorizonReference = Ellipsoid
GS.Location1 = 0
GS.Location2 = 0
GS.Location3 = 0
Create ContactLocator cl
cl.Target = sat
cl.Observers = {GS}
cl.Filename = 'SPKPropagation.report'
BeginMissionSequence
284
Reference Guide
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 supports several numerical techniques. 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 algorithm type, 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
Field
Description
Algorithm
The numerical method used to solve the boundary value problem.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
DerivativeMethod
String
NewtonRaphson, Broyden, ModifiedBroyden
set
NewtonRaphson
N/A
GUI, script
Chooses between one-sided and central differencing for numerically determining the derivative. Only used when Algorithm is set to NewtonRaphson.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
String
ForwardDifference,
CentralDifference
set
ForwardDifference
N/A
GUI, script
BackwardDifference,
285
Reference Guide
DifferentialCorrector
Field
Description
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
Allowed Values
Access
Default Value
Units
Interfaces
ReportFile
Specifies the path and file name for the DifferentialCorrector report.
The report is only generated if ShowProgress is set to true.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
ReportStyle
String
Filename consistent with OS
set
DifferentialCorrectorDCName.data,
where DCname is the name of the DifferentialCorrector
N/A
GUI, script
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
Allowed Values
Access
Default Value
Units
Interfaces
286
Integer
Integer >= 1
set
25
N/A
GUI, script
String
Normal, Concise, Verbose, Debug
set
Normal
N/A
GUI, script
DifferentialCorrector
Reference Guide
Field
Description
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
Allowed Values
Access
Default Value
Units
Interfaces
String
true, false
set
true
N/A
GUI, script
GUI
The DifferentialCorrector dialog box allows you to specify properties of a DifferentialCorrector
such as the numerical algorithm, 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
Supported Algorithm Details
GMAT supports several algorithms for solving boundary value problems including Newton Raphson, Broyden, and Modified Broyden. These algorithms use finite differencing or other numerical
287
Reference Guide
DifferentialCorrector
approximations to compute the Jacobian of the constraints and independent variables. The default
algorithm is currently NewtonRaphson. Brodyen’s method and ModifiedBroyden usually take
more iterations but fewer function evaluations than NewtonRaphson and so are often faster. A
description of each algorithm is provided below. We recommend trying different algorithm options
for your application to determine which algorithm provides the best balance of performance and
robustness.
Newton-Raphson
The NewtonRaphson algorithm is a quasi-Newton method that computes the Jacobian using finite
differencing. GMAT supports forward, central, and backward differencing to compute the Jacobian.
Broyden
Broyden’s method uses the slope between state iterations as an approximation of the first derivative
instead of numerically calculating the first derivative using finite differencing. This results in substantially fewer function evaluations. The Broyden iterate is updated using the following equation.
ModifiedBroyden
The modified Broyden’s method updates the inverse of the Jacobian matrix to avoid numerical
issues in matrix inversion when solving near singular problems. Like Broyden’s method, it requires
fewer function evaluations than the NewtonRaphson algorithm. The inverse of the Jacobian, H,
is updated using the following equation,
where
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.
288
DifferentialCorrector
Reference Guide
Examples
Create a DifferentialCorrector configured to use Broyden's method and use it to solve for an
apogee raising maneuver.
Create Spacecraft aSat
Create Propagator aProp
Create ImpulsiveBurn aDeltaV
Create OrbitView a3DPlot
a3DPlot.Add = {aSat,Earth};
Create DifferentialCorrector aDC
aDC.Algorithm = 'Broyden'
BeginMissionSequence
Propagate aProp(aSat){aSat.Periapsis}
Target aDC
Vary aDC(aDeltaV.Element1 = 0.01)
Maneuver aDeltaV(aSat)
Propagate aProp(aSat){aSat.Apoapsis}
Achieve aDC(aSat.RMAG = 12000)
EndTarget
To see further examples for how the DifferentialCorrector object is used in conjunction with Target, Vary, and Achieve commands to solve orbit problems, see the Target command examples.
289
290
Reference Guide
ElectricTank
A model of a tank containing fuel for an electric propulsion system
Description
An ElectricTank is a model of a tank and is required for finite burns employing an electric propulsion system. To use an ElectricTank, you must first create the tank, and then attach it to the desired
Spacecraft and associate it with an ElectricThruster as shown in the example below. Additionally
you must create a SolarPowerSystem or NuclearPowerSystem and attach it to the Spacecraft.
For a complete descripton of how to configure all Resources required for electric propulsion modelling, see the Tutorial named Electric Propulsion
See Also ElectricThruster,NuclearPowerSystem,SolarPowerSystem
Fields
Field
Description
AllowNegativeFuelMass
This field allows the ElectricTank 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
Allowed Values
Access
Default Value
Units
Interfaces
FuelMass
Boolean
true, false
set
false
N/A
GUI, script
The mass of fuel in the tank.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
Real
Real > 0
set, get
756
kg
GUI, script
GUI
The ElectricTank dialog box allows you to specify properties of a fuel tank. The layout of the
ElectricTank dialog box is shown below.
291
Reference Guide
ElectricTank
Remarks
Use of ElectricTank Resource in Conjunction with Maneuvers
An ElectricTank is used in conjunction with finite maneuvers. To implement a finite maneuver,
you must first create both an ElectricThruster and a FiniteBurn resource. You must also associate the ElectricTank with the ElectricThruster resource and you must associate the ElectricThruster with the FiniteBurn resource. The finite maneuver is implemented using the BeginFiniteBurn/EndFiniteBurn commands. See the BeginFiniteBurn/EndFiniteBurn command
documentation for worked examples on how the ElectricTank resource is used in conjunction with
finite maneuvers.
For a complete descripton of how to configure all Resources required for electric propulsion modelling, see the Tutorial named Electric Propulsion
Behavior When Configuring Tank and Attached Tank Properties
Create a default ElectricTank and attach it to a Spacecraft and ElectricThruster.
% Create the ElectricTank Resource
Create ElectricTank aTank
aTank.AllowNegativeFuelMass = false
aTank.FuelMass = 756
% Create an ElectricThruster and assign it a ElectricTank
Create ElectricThruster aThruster
aThruster.Tank = {aTank}
% Add the ElectricTank 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 ElectricTank 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.
292
ElectricTank
Reference Guide
% Add the ElectricTank and ElectricThruster 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
BeginMissionSequence
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 ElectricTank and attach it to a Spacecraft and ElectricThruster.
% Create the ElectricTank Resource
Create ElectricTank aTank
aTank.AllowNegativeFuelMass = false
aTank.FuelMass = 756
% Create an ElectricThruster and assign it a ElectricTank
Create ElectricThruster aThruster
aThruster.Tank = {aTank}
% Add the ElectricTank and ElectricThruster to a Spacecraft
Create Spacecraft aSpacecraft
aSpacecraft.Tanks = {aTank}
293
Reference Guide
aSpacecraft.Thrusters = {aThruster}
BeginMissionSequence
294
ElectricTank
Reference Guide
ElectricThruster
An electric thruster model
Description
The ElectricThruster resource is a model of an electric thruster which supports several models for
thrust and mass flow computation. The ElecticThruster model also allows you to specify properties such as a duty cycle and scale factor and to connect an ElectricThruster with an ElectricTank.
You can flexibly define the direction of the thrust by specifying the thrust components in coordinate systems such as (locally defined) SpacecraftBody or LVLH, or by choosing any configured
CoordinateSystem resource.
For a complete descripton of how to configure all Resources required for electric propulsion modelling, see the Tutorial named Electric Propulsion
See Also ElectricTank, NuclearPowerSystem, SolarPowerSystem
Fields
Field
Description
Axes
Allows the user to define a spacecraft centered set of axes for the ElectricThruster. This field cannot be modified in the Mission Sequence
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
ConstantThrust
Thrust value used ThrustModel is set to ConstantThrustAndIsp.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
CoordinateSystem
Reference Array
VNB, LVLH, MJ2000Eq, SpacecraftBody
set
VNB
N/A
GUI, script
Real
Real > 0
set, get
0.237
N
GUI, script
Determines what coordinate system the orientation parameters, ThrustDirection1, ThrustDirection2, and ThrustDirection3 refer to. This
field cannot be modified in the Mission Sequence.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
Reference Array
Local, EarthMJ2000Eq, EarthMJ2000Ec,
EarthFixed, or any user defined system
set
Local
N/A
GUI, script
295
Reference Guide
ElectricThruster
Field
Description
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
Allowed Values
Access
Default Value
Units
Interfaces
DutyCycle
Fraction of time that the thrusters are on during a maneuver. The thrust
applied to the spacecraft is scaled by this amount. Note that this scale
factor also affects mass flow rate.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
FixedEfficiency
Real Number
Real > 0
set, get
9.81
m/s2
GUI, script
Thruster specific impulse. Only used when ThrustModel is set to FixedEfficiency or ConstantThrustAndIsp.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
296
Real
Real > 0
set, get
0.7
Decimal Percent
GUI, script
Value of the gravitational acceleration used for the FuelTank/Thruster calculations.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
Isp
Real Number
0 <= Real <= 1
set, get
1
N/A
GUI, script
Thruster efficiency. Only used when ThrustModel is FixedEfficiency.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
GravitationalAccel
Boolean
true, false
set
false
N/A
GUI, script
Real
Real > 0
set, get
4200
seconds
GUI, script
ElectricThruster
Reference Guide
Field
Description
MassFlowCoeff1
Mass flow coefficient.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
MassFlowCoeff2
Mass flow coefficient.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
MassFlowCoeff3
Real
Real Number
set, get
-0.09956
See Mathematical Models
GUI, script
Mass flow coefficient.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
MassFlowCoeff5
Real
Real Number
set, get
0.05717
See Mathematical Models
GUI, script
Mass flow coefficient.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
MassFlowCoeff4
Real
Real Number
set, get
-0.004776
See Mathematical Models
GUI, script
Real
Real Number
set, get
0.03211
See Mathematical Models
GUI, script
Mass flow coefficient.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
Real
Real Number
set, get
2.13781
See Mathematical Models
GUI, script
297
Reference Guide
ElectricThruster
Field
Description
MaximumUsablePower
The maximum power the thruster can use to generate thrust. Power provided above MaximumUsablePower is not used in the thrust model.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
MinimumUsablePower
The minimum power the thruster can use to generate thrust. If power provided to thruster is below MinimumUsablePower, no thrust is generated.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
MixRatio
Access
Default Value
Units
Interfaces
Array
Array of real numbers with same length as number of tanks in the Tank array
set
[1]
N/A
GUI, script
This field, used in conjunction with the Axes field, allows the user to define
a spacecraft centered set of axes for the ElectricThruster. Origin has
no affect when a Local coordinate system is used and the Axes are set
to MJ2000Eq or SpacecraftBody. This field cannot be modified in the
Mission Sequence.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
298
Real
Real > 0, Real > MinimumUsablePower
set, get
0.638
kW
GUI, script
The mixture ratio employed to draw fuel from multiple tanks. For example,
if there are two tanks and MixRatio is set to [2 1], then twice as much fuel
will be drawn from tank one as from tank 2 in the Tank list. Note, if a
MixRatio is not supplied, fuel is drawn from tanks in equal amounts, (the
MixRatio is set to a vector of ones the same length as the Tank list).
Data Type
Allowed Values
Origin
Real
Real > 0, Real < MinimumUsablePower
set, get
7.266
kW
GUI, script
Reference Array
Sun, Mercury, Venus, Earth, Luna,
Mars,Jupiter, Saturn, Uranus, Neptune, Pluto
set
Earth
N/A
GUI, script
ElectricThruster
Reference Guide
Field
Description
Tanks
ElectricTank from which the ElectricThruster draws propellant from.
In a script command, an empty list, e.g., Thruster1.Tank = {}, is
NOT allowed. Via the script, if you wish to indicate that no ElectricTank
is associated with an ElectricThruster, do not include commands such as
Thruster1.Tank = ... in your script. This field cannot be modified
in the Mission Sequence.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
ThrustCoeff1
Thrust coefficient.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
ThrustCoeff2
Real
Real Number
set, get
2.96519
See Mathematical Models
GUI, script
Thrust coefficient.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
ThrustCoeff4
Real
Real Number
set, get
-5.19082
See Mathematical Models
GUI, script
Thrust coefficient.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
ThrustCoeff3
Reference Array
User defined list of FuelTank(s).
set
N/A
N/A
GUI, script
Real
Real Number
set, get
-14.41789
See Mathematical Models
GUI, script
Thrust coefficient.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
Real
Real Number
set, get
54.05382
See Mathematical Models
GUI, script
299
Reference Guide
ElectricThruster
Field
Description
ThrustCoeff5
Thrust coefficient.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
ThrustDirection1
X component of the spacecraft thrust vector direction.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
ThrustDirection2
Real
Real Number
set, get
0
N/A
GUI, script
The type of thruster model. See Mathematical Models for a detailed description of the options.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
300
Real
Real Number
set, get
1
N/A
GUI, script
Z component of the spacecraft thrust vector direction.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
ThrustModel
Real
Real Number
set, get
1
N/A
GUI, script
Y component of the spacecraft thrust vector direction.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
ThrustDirection3
Real
Real Number
set, get
-0.00100092
See Mathematical Models
GUI, script
String
ThrustMassPolynomial,
ConstantThrustAndIsp,FixedEfficiency
set, get
ThrustMassPolynomial
N/A
GUI, script
ElectricThruster
Reference Guide
Field
Description
ThrustScaleFactor
ThrustScaleFactor is a scale factor that is multiplied by the thrust vector,
for a given thruster, before the thrust vector is added into the total acceleration. Note that the value of this scale factor does not affect the mass
flow rate.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
Real Number
Real >= 0
set, get
1
N/A
GUI, script
Interactions
Command or Resource
Description
BeginFiniteBurn/EndFiniteBurn command
Use these commands, which require a Spacecraft and a FiniteBurn name
as input, to implement a finite burn.
ElectricTank
source
re- This resource contains the fuel used to power the ElectricThruster specified by the FiniteBurn resource.
FiniteBurn
source
re- When using the BeginFiniteBurn/EndFiniteBurn commands, you must
specify which FiniteBurn resource to implement. The FiniteBurn resource
specifies which ElectricThruster(s) to use for the finite burn.
Spacecraft resource When using the BeginFiniteBurn/EndFiniteBurn commands, you must
specify which Spacecraft to apply the finite burn to.
Propagate
mand
com- In order to implement a non-zero finite burn, a Propagate statement must
occurr within the BeginFiniteBurn and EndFiniteBurn statements.
GUI
The ElectricThruster dialog box allows you to specify properties of an ElectricThruster including
the Coordinate System of the thrust acceleration direction vector, the thrust magnitude and Isp
coefficients, and choice of ElectricTank. The layout of the ElectricThruster dialog box is shown
below.
301
Reference Guide
ElectricThruster
When configuring the Coordinate System field, you can choose between existing coordinate systems or use locally defined coordinate systems. The Axes field is only active if Coordinate System
302
ElectricThruster
Reference Guide
is set to Local. The Origin field is only active if Coordinate System is set to Local and Axes is
set to either VNB or LVLH.
Selecting the Configure Polynomials button brings up the following dialog box where you may
input the coefficients for the ElectricThruster polynomial.
Similarly, clicking the Configure Polynomials also allows you to edit mass flow coefficients as
shown below.
Remarks
Mathematical Models
The ElectricThruster model supports several models for computation of thrust and and mass flow
rate and the model used is set by the ThrustModel field. When ThrustModel is set to ThrustMassPolynomial, the following polynomials are used to compute thrust and mass flow rate
303
Reference Guide
ElectricThruster
where P is the power provided to the thruster which is computed using the power logic defined on
the FiniteBurn resource, f_d is duty cycle, f_s is thrust scale factor, R_iT is the rotation matrix from
the thrust coordinate system to the inertial system, and T_hat is the thrust unit vector. By industry
convention, the mass flow rate and thrust polynomial equations are in mg/s and milli-Newtons
respectively. GMAT internally converts the units to be consistent with the equations of motion.
When ThrustModel is set to ConstantThrustAndIsp, the following polynomials are used to compute thrust and mass flow rate
where C_t1 is set using the ConstantThrust field, Isp is set using the Isp field, f_d is duty cycle, f_s
is thrust scale factor, R_iT is the rotation matrix from the thrust coordinate system to the inertial
system, and T_hat is the thrust unit vector. Note, by industry convention, the mass flow rate and
thrust polynomial equations are in mg/s and milli-Newtons respectively. GMAT internally converts
the units to be consistent with the equations of motion.
When ThrustModel is set to FixedEfficiency, the following polynomials are used to compute
thrust and mass flow rate
where P is the power provided to the thruster which is computed from the power logic defined
on the FiniteBurn Resource. "Eta" is the FixedEfficiency setting, f_d is duty cycle, f_s is thrust
scale factor, R_iT is the rotation matrix from the thrust coordinate system to the inertial system,
and T_hat is the thrust unit vector.
Use of Thruster Resource in Conjunction With Maneuvers
An ElectricThruster resource is used only in association with finite maneuvers. To implement
a finite maneuver, you must first create both an ElectricTank and a FiniteBurn resource. You
must also associate an ElectricTank with the ElectricThruster resource and you must associate an
ElectricThruster with the FiniteBurn resource. The actual finite maneuver is implemented using
the BeginFiniteBurn/EndFiniteBurn commands.
For a complete descripton of how to configure all Resources required for electric propulsion modelling, see the Tutorial named Electric Propulsion
304
ElectricThruster
Reference Guide
Local Coordinate Systems
Here, a Local coordinate system is defined as one that we configure "locally" using the ElectricThruster 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 thrust
acceleration direction vector, ThrustDirection1-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 completes the right-handed set.
Similarly, Local Vertical Local Horizontal or LVLH is also a non-inertial coordinate system based
upon the motion of the spacecraft with respect to the Origin sub-field. Again, if we choose Earth as
the origin, then the X-axis of this coordinate system is the position of the spacecraft with respect to
the Earth, the Z-axis is the instantaneous orbit normal (with respect to the Earth) of the spacecraft,
and the Y-axis completes the right-handed set.
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 attitude system of 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.
Caution Regarding Force Model Discontinuties
Note that when modellign shadows on a SolarPowerSystem Resource, it is possible that there is
not enough power available to power an ElectricThruster. This occurs when the power available
from the SolarPowerSystem, or the power distributed to the thruster, is less than MinimumUsablePower. When this occurs, the thruster model turns off thrust and this can cause a discontinuity
in the force model. To avoid this, you must propagate to the boundary and switch propagators, or
configure the Propagator to continue propagating if a poor step occurs.
Examples
Create a default ElectricTank and an ElectricThruster that allows for fuel depletion, assign the
ElectricThruster the default ElectricTank, and attach both to a Spacecraft.
% Create an ElectricTank Resource
Create ElectricTank anElectricTank
% Create an Electric Thruster Resource
Create ElectricThruster anElectricThruster
anElectricThruster.CoordinateSystem = Local
anElectricThruster.Origin = Earth
anElectricThruster.Axes = VNB
305
Reference Guide
anElectricThruster.ThrustDirection1 = 1
anElectricThruster.ThrustDirection2 = 0
anElectricThruster.ThrustDirection3 = 0
anElectricThruster.DutyCycle = 1
anElectricThruster.ThrustScaleFactor = 1
anElectricThruster.DecrementMass = true
anElectricThruster.Tank = {anElectricTank}
anElectricThruster.GravitationalAccel = 9.810000000000001
anElectricThruster.ThrustModel = ThrustMassPolynomial
anElectricThruster.MaximumUsablePower = 7.266
anElectricThruster.MinimumUsablePower = 0.638
anElectricThruster.ThrustCoeff1 = -5.19082
anElectricThruster.ThrustCoeff2 = 2.96519
anElectricThruster.ThrustCoeff3 = -14.4789
anElectricThruster.ThrustCoeff4 = 54.05382
anElectricThruster.ThrustCoeff5 = -0.00100092
anElectricThruster.MassFlowCoeff1 = -0.004776
anElectricThruster.MassFlowCoeff2 = 0.05717
anElectricThruster.MassFlowCoeff3 = -0.09956
anElectricThruster.MassFlowCoeff4 = 0.03211
anElectricThruster.MassFlowCoeff5 = 2.13781
anElectricThruster.FixedEfficiency = 0.7
anElectricThruster.Isp = 4200
anElectricThruster.ConstantThrust = 0.237
% Create a SolarPowerSystem Resource
Create SolarPowerSystem aSolarPowerSystem
% Create a Spacecraft Resource and attach hardware
Create Spacecraft DefaultSC
DefaultSC.Tanks = {anElectricTank}
DefaultSC.Thrusters = {anElectricThruster}
DefaultSC.PowerSystem = aSolarPowerSystem
BeginMissionSequence
306
ElectricThruster
Reference Guide
EclipseLocator
A Spacecraft eclipse event locator
Description
Note
EclipseLocator is a SPICE-based subsystem that uses a parallel configuration for the
solar system and celestial bodies from other GMAT components. For precision applications, care must be taken to ensure that both configurations are consistent. See Remarks for details.
An EclipseLocator is an event locator used to find solar eclipse events as seen by a Spacecraft.
By default, an EclipseLocator generates a text event report listing the beginning and ending times
of each event, along with the duration, eclipsing body, shadow type, and information about simultaneous and adjacent nested events. Eclipse location can be performed over the entire propagation
interval or over a subinterval, and can optionally adjust for light-time delay and stellar aberration.
Eclipse location can be performed with one or more CelestialBody resources as eclipsing (or occulting) bodies. Any configured CelestialBody can be used as an occulting body, including userdefined ones. Any type of eclipse can be found, including total (umbra), partial (penumbra), and
annular (antumbra). All selected occulting bodies are searched using the same selection for eclipse
types, search interval, and search options; to customize the options per body, use multiple EclipseLocator resources.
By default, the EclipseLocator searches the entire interval of propagation of the Spacecraft. To
search a custom interval, set UseEntireInterval to False and set InitialEpoch and FinalEpoch
accordingly. Note that these epochs are assumed to be Spacecraft epochs, and so must be valid
and within the Spacecraft ephemeris interval. If they fall outside the propagation interval of the
Spacecraft, GMAT will display an error.
The contact locator can optionally adjust for both light-time delay and stellar aberration, though
stellar aberration currently has no effect.
The event search is performed at a fixed step through the interval. You can control the step size
(in seconds) by setting the StepSize field. An appropriate choice for step size is no greater than the
duration of the minimum event you wish to find, or the minimum gap between events you want to
resolve, whichever is smaller. See Remarks for details.
GMAT uses the SPICE library for the fundamental event location algorithm. As such, all celestial
body data is loaded from SPICE kernels for this subsystem, rather than GMAT's own CelestialBody
shape and orientation configuration. See Remarks for details.
Unless otherwise mentioned, EclipseLocator fields cannot be set in the mission sequence.
See Also: CelestialBody, Spacecraft, ContactLocator, FindEvents
307
Reference Guide
EclipseLocator
Fields
Field
Description
EclipseTypes
Types of eclipses (shadows) to search for. May be Umbra (total eclipses),
Penumbra (partial eclipses), or Antumbra (annular eclipses).
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
Filename
Name and path of the eclipse report file. This field can be set in the mission
sequence.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
FinalEpoch
InitialEpoch
308
Enumeration array
Antumbra, Penumbra, Umbra
set
{Antumbra, Penumba, Umbra}
N/A
GUI, script
String
Valid file path
set
'EclipseLocator.txt'
N/A
GUI, script
Last epoch to search for eclipses, in the format specified by InputEpochFormat. The epoch must be a valid epoch in the Spacecraft
ephemeris interval. This field can be set in the mission sequence.
Data Type
Allowed Values
Access
Default Value
Units
String
Valid epoch in available spacecraft ephemeris
set
'21545.138'
ModifiedJulian epoch formats: days
Interfaces
Gregorian epoch formats: N/A
GUI, script
First epoch to search for eclipses, in the format specified by InputEpochFormat. The epoch must be a valid epoch in the Spacecraft
ephemeris interval. This field can be set in the mission sequence.
Data Type
Allowed Values
Access
Default Value
Units
String
Valid epoch in available spacecraft ephemeris
set
'21545'
ModifiedJulian epoch formats: days
Interfaces
Gregorian epoch formats: N/A
GUI, script
EclipseLocator
Reference Guide
Field
Description
OccultingBodies
List of occulting bodies to search for eclipses. Can be any number of
GMAT CelestialBody-type resources, such as Planet, Moon, Asteroid,
etc. Note that an occulting body must have a mass (e.g. not LibrationPoint or Barycenter).
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
RunMode
Mode of event location execution. 'Automatic' triggers event location
to occur automatically at the end of the run. 'Manual' limits execution
only to the FindEvents command. 'Disabled' turns of event location
entirely.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
Spacecraft
Enumeration
Automatic, Manual, Disabled
set
'Automatic'
N/A
GUI, script
The observing Spacecraft resource to search for eclipses.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
StepSize
List of CelestialBody resources (e.g. Planet, Asteroid, Moon, etc.)
Any existing CelestialBody-class resources
set
Empty list
N/A
GUI, script
Spacecraft resource
Any existing Spacecraft resource
set
First configured Spacecraft resource
N/A
GUI, script
Step size of event locator. See Remarks for discussion of appropriate values.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
Real
StepSize > 0
set
10
s
GUI, script
309
Reference Guide
EclipseLocator
Field
Description
UseEntireInterval
Search the entire available Target ephemeris interval. This field can be set
in the mission sequence.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
Boolean
true, false
set
true
N/A
GUI, script
UseLightTimeDelay Use light-time delay in the event-finding algorithm.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
Boolean
true, false
set
true
N/A
GUI, script
UseStellarAberration Use stellar aberration in addition to light-time delay in the event-finding
algorithm. Light-time delay must be enabled. Stellar aberration currently
has no effect on eclipse searches.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
WriteReport
Write an event report when event location is executed. This field can be
set in the mission sequence.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
310
Boolean
true, false
set
true
N/A
GUI, script
Boolean
true, false
set
true
N/A
GUI, script
EclipseLocator
Reference Guide
GUI
The default EclipseLocator GUI for a new resource is shown above. You can choose one Spacecraft from the list, which is populated by all the Spacecraft resources currently configured in the
mission. In the Occulting Bodies list, you can check the box next to all CelestialBody resources
you want to search for eclipses. This list shows all celestial bodies currently configured in the mission.
In the Eclipse Types list, choose the types of eclipses to search for. Note that each selection will
increase the duration of the search.
You can configure the output via Filename, Run Mode, and Write Report near the bottom. If
Write Report is enabled, a text report will be written to the file specified in Filename. The search
will execute during FindEvents commands (for Manual or Automatic modes) and automatically
at the end of the mission (for Automatic mode), depending on the Run Mode.
You can configure the search interval via the options in the upper right. Uncheck Use Entire Interval to set the search interval manually. See the Remarks section for considerations when setting
the search interval.
You can control the search algorithm via the options in the bottom right. Configure light-time and
stellar aberration via the check boxes next to each, and select the signal direction via the Light-time
direction selection.
To control the fidelity and execution time of the search, set the Step size appropriately. See the
Remarks section for details.
311
Reference Guide
EclipseLocator
Remarks
Data configuration
The EclipseLocator implementation is based on the NAIF SPICE toolkit, which uses a different mechanism for environmental data such as celestial body shape and orientation, planetary
ephemerides, body-specific frame definitions, and leap seconds. Therefore, it is necessary to maintain two parallel configurations to ensure that the event location results are consistent with GMAT's
own propagation and other parameters. The specific data to be maintained is:
• Planetary shape and orientation:
• GMAT core: CelestialBody.EquatorialRadius, Flattening, SpinAxisRAConstant,
SpinAxisRARate, etc.
• ContactLocator: SolarSystem.PCKFilename, CelestialBody.PlanetarySpiceKernelName
• Planetary ephemeris:
• GMAT
core:
SolarSystem.DEFilename,
or
(SolarSystem.SPKFilename,
CelestialBody.OrbitSpiceKernelName, CelestialBody.NAIFId)
• ContactLocator: SolarSystem.SPKFilename, CelestialBody.OrbitSpiceKernelName,
CelestialBody.NAIFId
• Body-fixed frame:
• GMAT core: built-in
• ContactLocator: CelestialBody.SpiceFrameId, CelestialBody.FrameSpiceKernelName
• Leap seconds:
• GMAT core: startup file LEAP_SECS_FILE setting
• ContactLocator: SolarSystem.LSKFilename
See SolarSystem and CelestialBody for more details.
Search interval
The EclipseLocator search interval can be specified either as the entire ephemeris interval of the
Spacecraft, or as a user-defined interval. If UseEntireInterval is true, the search is performed over
the entire ephemeris interval of the Spacecraft, including any gaps or discontinuities. If UseEntireInterval is false, the provided InitialEpoch and FinalEpoch are used to form the search interval directly. The user must ensure than the provided interval results in valid Spacecraft and CelestialBody ephemeris epochs.
Run modes
The EclipseLocator works in conjunction with the FindEvents command: the EclipseLocator resource defines the configuration of the event search, and the FindEvents command executes the search at a specific point in the mission sequence. The mode of interaction is defined by
EclipseLocator.RunMode, which has three options:
• Automatic: All FindEvents commands are executed as-is, plus an additional FindEvents is
executed automatically at the end of the mission sequence.
• Manual: All FindEvents commands are executed as-is.
• Disabled: FindEvents commands are ignored.
312
EclipseLocator
Reference Guide
Search algorithm
The EclpseLocator uses the NAIF SPICE GF (geometry finder) subsystem to perform event location. Specifically, the following call is used for the search:
• gfoclt_c: For third-body occultation searches
This function implements a fixed-step search method through the interval, with an embedded rootlocation step if an event is found. StepSize should be set equal to the length of the minimum-duration event to be found, or equal to the length of the minimum-duration gap between events,
whichever is smaller. To guarantee location of 10-second eclipses, or 10-second gaps between adjacent eclipses, set StepSize = 10.
For details, see the reference documentation for the function linked above.
Report format
When WriteReport is enabled, the EclipseLocator outputs an event report at the end of each
search execution. The report contains the following data:
• Spacecraft name
• For each event:
• Event start time (UTC)
• Event stop time (UTC)
• Event duration (s)
• Occulting body name
• Eclipse type
• Total event number
• Total duration
• Number of individual events
• Number of total events
• Maximum total duration
• Eclipse number of total duration
The report makes the distinction between an individual event and a total event.
• An individual event is a single continuous event of a single type (umbra, penumbra, etc.) from a single
occulting body. Individual events can be nested for a single occulting body, such as a penumbra
event followed immediately by an umbra event, or they can be nested from multiple occulting
bodies, such as a Luna eclipse occuring in the middle of an Earth eclipse.
• A total event is the entire set of nested individual events. The total event is given a single number,
and the total duration is reported in the output file.
Event location with SPK propagator
When using the SPK propagator, you load one or more SPK ephemeris files using the
Spacecraft.OrbitSpiceKernelName field. For the purposes of event location, this field causes the appropriate ephemeris files to be loaded automatically on run, and so use of the Propagation command
is not necessary. This is an easy way of performing event location on an existing SPK ephemeris
file. See the example below.
313
Reference Guide
EclipseLocator
Examples
Perform a basic eclipse search in LEO:
SolarSystem.EphemerisSource = 'DE421'
Create Spacecraft sat
sat.DateFormat = UTCGregorian
sat.Epoch = '15 Sep 2010 16:00:00.000'
sat.CoordinateSystem = EarthMJ2000Eq
sat.DisplayStateType = Keplerian
sat.SMA = 6678.14
sat.ECC = 0.001
sat.INC = 0
sat.RAAN = 0
sat.AOP = 0
sat.TA = 180
Create ForceModel fm
fm.CentralBody = Earth
fm.PrimaryBodies = {Earth}
fm.GravityField.Earth.PotentialFile = 'JGM2.cof'
fm.GravityField.Earth.Degree = 0
fm.GravityField.Earth.Order = 0
fm.GravityField.Earth.EarthTideModel = 'None'
fm.Drag.AtmosphereModel = None
fm.PointMasses = {}
fm.RelativisticCorrection = Off
fm.SRP = Off
Create Propagator prop
prop.FM = fm
prop.Type = RungeKutta89
Create EclipseLocator el
el.Spacecraft = sat
el.Filename = 'Simple.report'
el.OccultingBodies = {Earth}
el.EclipseTypes = {'Umbra', 'Penumbra', 'Antumbra'}
BeginMissionSequence
Propagate prop(sat) {sat.ElapsedSecs = 10800}
Perform an eclipse event search from a Mars orbiter, with Phobos, Earth, and Moon eclipses:
% Mars orbiter with annular eclipses of Earth and Moon.
SolarSystem.EphemerisSource = 'SPICE'
SolarSystem.SPKFilename = 'de421.bsp'
314
EclipseLocator
Reference Guide
Mars.NAIFId = 499
Mars.OrbitSpiceKernelName = {'../data/planetary_ephem/spk/mar063.bsp'}
Create Spacecraft sat
sat.DateFormat = UTCGregorian
sat.Epoch = '10 May 1984 00:00:00.000'
sat.CoordinateSystem = MarsMJ2000Eq
sat.DisplayStateType = Keplerian
sat.SMA = 6792.38
sat.ECC = 0
sat.INC = 45
sat.RAAN = 0
sat.AOP = 0
sat.TA = 0
Create ForceModel fm
fm.CentralBody = Mars
fm.PrimaryBodies = {Mars}
fm.GravityField.Mars.PotentialFile = 'Mars50c.cof'
fm.GravityField.Mars.Degree = 0
fm.GravityField.Mars.Order = 0
fm.Drag.AtmosphereModel = None
fm.PointMasses = {}
fm.RelativisticCorrection = Off
fm.SRP = Off
Create Propagator prop
prop.FM = fm
prop.Type = RungeKutta89
Create CoordinateSystem MarsMJ2000Eq
MarsMJ2000Eq.Origin = Mars
MarsMJ2000Eq.Axes = MJ2000Eq
Create Moon Phobos
Phobos.CentralBody = 'Mars'
Phobos.PosVelSource = 'SPICE'
Phobos.NAIFId = 401
Phobos.OrbitSpiceKernelName = {'mar063.bsp'}
Phobos.SpiceFrameId = 'IAU_PHOBOS'
Phobos.EquatorialRadius = 13.5
Phobos.Flattening = 0.3185185185185186
Phobos.Mu = 7.093399e-004
Create Moon Deimos
Deimos.CentralBody = 'Mars'
Deimos.PosVelSource = 'SPICE'
Deimos.NAIFId = 402
315
Reference Guide
EclipseLocator
Deimos.OrbitSpiceKernelName = {'mar063.bsp'}
Deimos.EquatorialRadius = 7.5
Deimos.SpiceFrameId = 'IAU_DEIMOS'
Deimos.Flattening = 0.30666666666666664
Deimos.Mu = 1.588174e-004
Create EclipseLocator ec
ec.Spacecraft = sat
ec.OccultingBodies = {Mercury, Venus, Earth, Luna, Mars, Phobos, Deimos}
ec.Filename = 'EarthTransit.report'
BeginMissionSequence
Propagate prop(sat) {sat.ElapsedDays = 2}
Perform eclipse location on an existing SPK ephemeris file:
SolarSystem.EphemerisSource = 'DE421'
Create Spacecraft sat
sat.OrbitSpiceKernelName = {'../data/vehicle/ephem/spk/Events_Simple.bsp'}
Create EclipseLocator cl
cl.Spacecraft = sat
cl.OccultingBodies = {Earth}
cl.Filename = 'SPKPropagation.report'
BeginMissionSequence
316
Reference Guide
EphemerisFile
Generate spacecraft’s ephemeris data
Description
EphemerisFile is a user-defined resource that generates spacecraft’s ephemeris 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 CCSDS-OEM, SPK, Code-500 and STK .e (STK -TimePosVel) 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. 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
Field
Description
CoordinateSystem
Allows you to generate spacecraft ephemeris w.r.t the coordinate system
that you select for this field. Ephemeris can also be generated w.r.t a userspecified coordinate system. This field cannot be modified in the Mission
Sequence.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
EpochFormat
Enumeration
Any default coordinate system or a user-defined
coordinate system
set, get
EarthMJ2000Eq
N/A
GUI, script
The field allows you to set the type of the epoch that you choose to enter
for InitialEpoch and FinalEpoch fields. This field cannot be modified
in the Mission Sequence.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
Enumeration
Any of the following epoch formats: UTCGregorian UTCModJulian, TAIGregorian,
TAIModJulian, TTGregorian, TTModJulian,
A1Gregorian, A1ModJulian
Set
UTCGregorian
N/A
GUI, script
317
Reference Guide
EphemerisFile
Field
Description
FileFormat
Allows the user to generate ephemeris file in four available ephemeris formats: CCSDS-OEM, SPK, Code-500 or STK-TimePosVel (i.e. STK .e format). This field cannot be modified in the Mission Sequence.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
FileName
Allows the user to name the ephemeris file that is generated. File extensions for CCSDS-OEM, SPK, Code-500 and STK-TimePosVel ephemeris
types are *.oem, *.bsp, *.eph and *.e respectively. This field cannot be modified in the Mission Sequence.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
FinalEpoch
String
user-defined final epoch or Default Value
set
FinalSpacecraftEpoch
N/A
GUI, script
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
Allowed Values
Access
Default Value
Units
Interfaces
318
String
Valid File Path and Name
set
EphemerisFile1.eph
N/A
GUI, script
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
Allowed Values
Access
Default Value
Units
Interfaces
InitialEpoch
Enumeration
CCSDS-OEM, SPK, Code-500, STK-TimePosVel
Set
CCSDS-OEM
N/A
GUI, script
String
user-defined initial epoch or Default Value
set
InitialSpacecraftEpoch
N/A
GUI, script
EphemerisFile
Reference Guide
Field
Description
InterpolationOrder
Allows you to set the interpolation order for the available interpolator
methods (Lagrange or Hermite) for any of the ephemeris types. This
field cannot be modified in the Mission Sequence.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
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
Allowed Values
Access
Default Value
Units
Interfaces
Maximized
String
Lagrange for CCSDS-OEM, Code-500 and
STK-TimePosVel ephemeris types,Hermite for
SPK file
set
Lagrange
N/A
GUI, script
Allows the user to maximize the generated ephemeris file window. This
field cannot be modified in the Mission Sequence.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
OutputFormat
Integer
1 <= Integer Number <= 10
Set
7
N/A
GUI, script
Boolean
true,false
set
false
N/A
script
Allows the user to specify what type of format they want GSFC Code-500
ephmeris to be generated in. GSFC Code-500 ephemeris can be generated
in the PC or UNIX version. This field cannot be modified in the Mission
Sequence.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
String
PC, UNIX
Set
PC
N/A
GUI, script
319
Reference Guide
EphemerisFile
Field
Description
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
Allowed Values
Access
Default Value
Units
Interfaces
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
Allowed Values
Access
Default Value
Units
Interfaces
Spacecraft
Real array
Any Real number
set
[00]
N/A
script
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
Allowed Values
Access
Default Value
Units
Interfaces
320
Integer
Integer ≥ 0
set
0
N/A
script
String
Default spacecraft or any number of user-defined
spacecrafts or formations
set, get
DefaultSC
N/A
GUI, script
EphemerisFile
Reference Guide
Field
Description
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.
For CCSDS-OEM and STK-TimePosVel file formats, you can generate
ephemeris at either Integrator steps or fixed step size. For SPK file format,
GMAT lets you generate ephemeris at only raw integrator step sizes. For
Code-500 ephemeris file type, you can generate ephemeris at only fixed
step sizes. This field cannot be modified in the Mission Sequence.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
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
Allowed Values
Access
Default Value
Units
Interfaces
WriteEphemeris
Real
Real Number > 0.0 or equals Default Value
Set
IntegratorSteps for CCSDS-OEM, SPK and
STK-TimePosVel file formats and 60 seconds
for Code-500 file format
N/A
GUI, script
Real array
Any Real number
set
[00]
N/A
script
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
Allowed Values
Access
Default Value
Units
Interfaces
Boolean
true,false
set
true
Unit
GUI, script
GUI
The figure below shows the default settings for the EphemerisFile resource:
321
Reference Guide
EphemerisFile
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:
322
EphemerisFile
Reference Guide
Remarks
Behavior of Coordinate System Field for CCSDS, Code 500 and SPK File
Formats
If the selected CoordinateSystem uses MJ2000Eq axes, the CCSDS ephemeris file contains
“EME2000” for the REF_FRAME according to CCSDS convention. By CCSDS requirements, nonstandard 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.
For code 500 file format, J2000 epoch can be with reference to any central body that you select.
For code 500 and SPK file formats, GMAT can only write ephemeris for a coordinate system under
CoordinateSystem field that references MJ2000Eq axis type for any central body.
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
323
Reference Guide
EphemerisFile
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 CCSDS ephemeris is also generated
backwards.
Warning
The Code500 ephemeris file requires fixed time steps and has a pre-defined format
for handling chunks of ephemeris data. The format does not allow chunking to stop
and start at state discontinuities that occur at impulsive maneuvers. GMAT's current
behavior is to interpolate across those discontinuities as the code 500 format does not
elegantly support ephemerides with discontinuities. This is acceptable for small maneuvers but becomes less accurate as the maneuvers grow in magnitude. We recommend
using more modern ephemeris file formats for this reasson.
Similar to CCSDS ephemeris format, the STK-TimePosVel ephemeris is also generated in separate
chunks of ephemeris data whenever an event such as an impulsive or a finite maneuver takes place
or a change in dynamic models occurs. However, unlike the CCSDS ephemeris, STK-TimePosVel
ephemeris is not generated during backward propagations and only forward propagation ephemeris
is reported.
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
324
EphemerisFile
Reference Guide
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 the Ephemeris File Formats:
For CCSDS file formats, whenever there is not enough raw data available to support the requested
interpolation type and order, GMAT 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. GMAT does not perform any interpolation for SPK files as SPK contains
its own interpolation. As a result, InitialEpoch and FinalEpoch fields behave differently for SPK
ephemerides. The first epoch on the file is the first step after InitialEpoch. The last epoch on the
file is the last step before FinalEpoch.
For code 500 file formats, you can set the interpolation order and currently GMAT supports Lagrange as the available interpolator method. For code 500 file formats, if there is not enough raw
data available to support interpolation type and order, GMAT will throw an error message and stop
interpolation.
For the STK-TimePosVel ephemeris format, whenever there is not enough raw data available to
support the generation of ephemeris at the requested interpolation order and fixed step size, GMAT
will internally adjust the interpolation order such that at least the beginning and the last ephemeris
points are reported in the STK .e ephemeris file. This new interpolation order will be reported at
STK . e ephemeris's header data.
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.
The Toggle command can be used on all four ephemeris types that GMAT supports.
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'
325
Reference Guide
EphemerisFile
BeginMissionSequence
Toggle anEphmerisFile
Propagate aProp(aSat)
Toggle anEphmerisFile
Propagate aProp(aSat)
Off
{aSat.ElapsedDays = 2}
On
{aSat.ElapsedDays = 4}
Behavior of Code 500 Ephemeris File During Discontinuous & Iterative
Processes
Code 500 ephemeris file follows the ephemeris format and definitions that have been defined in
Flight Dynamics Division (FDD) Generic Data Product Formats Interface Control Document.
Unlike CCSDS ephemeris file, code 500 ephemeris does not support separate chunks in the data blocks whenever discontinuous or discrete mission events such as impulsive/finite maneuvers,
change in dynamics or assignment command takes place. Rather, code 500 ephemeris is generated
all in one continuous data block regardless of any number of mission events that may occur between
initial and final epochs of ephemeris file. Furthermore, when a mission sequence employs iterative
processes such as differential correction or optimization, GMAT will only write the ephemeris for
the final solution from the iterative processes. Code 500 ephemeris does not allow non-monotonic
ephemeris generation and an exception will be thrown if propagation direction changes. Furthermore, any discontinuities created by assignments may result in invalid code 500 files.
Code 500 Ephemeris Header Records
The standard format for Code 500 ephemeris files has a logical record length of 2800 bytes. Code
500 files have two header records, ephemeris header record 1 and ephemeris record 2, followed by
as many ephemeris data records as required for the file timespan. Many parameters in ephemeris
file's header records are mandatory while some fields are optional. GMAT's Code 500 ephemeris
header records only specifies fields that are mandatory and optional fields have not been included.
Code 500's ephemeris header record 1 is mandatory while ephemeris record 2 is optional. Complete
description of ephemeris format and list of mandatory and optional ephemeris header record parameters is defined in Flight Dynamics Division (FDD) Generic Data Product Formats Interface Control Document. In GMAT, only required fields have been written in header record 1 while header record 2 is
left blank. Table below lists header record 1's required fields and any additional comments pertaining
to that field.
326
Required Fields
Comments
productId
'EPHEM '
satId
123.000000
timeSystemIndicator
2.000000
StartDateOfEphem_YYYMMDD
value depends on run time
startDayCountOfYear
value depends on run time
startSecondsOfDay
value depends on run time
endDateOfEphem_YYYMMDD
value depends on run time
endDayCountOfYear
value depends on run time
EphemerisFile
Reference Guide
Required Fields
Comments
endSecondsOfDay
value depends on run time
stepSize_SEC
value depends on run time
startYYYYMMDDHHMMSSsss.
value depends on run time
endYYYYMMDDHHMMSSsss.
value depends on run time
tapeId
'STANDARD'
sourceId
'GTDS '
headerTitle
'
centralBodyIndicator
value depends on run time
refTimeForDUT_YYMMDD
570918.000000
coordSystemIndicator1
'2000'
coordSystemIndicator2
4
orbitTheory
'COWELL '
timeIntervalBetweenPoints_DUT
value depends on run time
timeIntervalBetweenPoints_SEC
value depends on run time
outputIntervalIndicator
1
epochTimeOfElements_DUT
value depends on run time
epochTimeOfElements_DAY.
value depends on run time
epochA1Greg.
value depends on run time
epochUtcGreg.
value depends on run time
yearOfEpoch_YYY
value depends on run time
monthOfEpoch_MM
value depends on run time
dayOfEpoch_DD
value depends on run time
hourOfEpoch_HH
value depends on run time
minuteOfEpoch_MM
value depends on run time
secondsOfEpoch_MILSEC
value depends on run time
keplerianElementsAtEpoch_RAD[0]
value depends on run time
keplerianElementsAtEpoch_RAD[1]
value depends on run time
keplerianElementsAtEpoch_RAD[2]
value depends on run time
keplerianElementsAtEpoch_RAD[3]
value depends on run time
keplerianElementsAtEpoch_RAD[4]
value depends on run time
keplerianElementsAtEpoch_RAD[5]
value depends on run time
cartesianElementsAtEpoch_DULT[0]
value depends on run time
cartesianElementsAtEpoch_DULT[1]
value depends on run time
cartesianElementsAtEpoch_DULT[2]
value depends on run time
cartesianElementsAtEpoch_DULT[3]
value depends on run time
327
Reference Guide
EphemerisFile
Required Fields
Comments
cartesianElementsAtEpoch_DULT[4]
value depends on run time
cartesianElementsAtEpoch_DULT[5]
value depends on run time
startTimeOfEphemeris_DUT
value depends on run time
endTimeOfEphemeris_DUT
value depends on run time
timeIntervalBetweenPoints_DUT
value depends on run time
dateOfInitiationOfEphemComp_YYYMMDD value depends on run time
timeOfInitiationOfEphemComp_HHMMSS
value depends on run time
utcTimeAdjustment_SEC
0.000000
Pecession/Nutation indicator
1
For ephemeris header record 1, there are some required fields that have not been tabulated in
GMAT's Code 500 ephemeris header record 1. These fields that have not been tabulated in header
record 1 are listed in the table below. 0.0 indicates "used" and 1.0 means "not used".
Required Fields
Comments
Zonal and tesseral harmonics indicator
1.0
Lunar gravitation perturbation indicator
1.0
Solar radiation perturbation indicator
1.0
Solar gravitation perturbation indicator
1.0
Atmospheric drag perturbation indicator
1.0
Greenwich hour angle at epoch
1.0
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’:
328
EphemerisFile
Reference Guide
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}
This example shows how to generate a simple STK-TimePosVel (i.e. STK .e) ephemeris file.
Ephemeris file is generated for 1 day of propagation, then a simple impulsive maneuver takes place
and spacecraft propagates for another day. This ephemeris is generated at raw integrator steps.
Create Spacecraft aSat
Create Propagator aProp
Create ImpulsiveBurn IB
IB.Element1 = 0.5
Create EphemerisFile anEphmerisFile
anEphmerisFile.Spacecraft = aSat
anEphmerisFile.Filename = 'EphemerisFile.e'
anEphmerisFile.FileFormat = STK-TimePosVel
BeginMissionSequence
Propagate aProp(aSat) {aSat.ElapsedDays = 1}
Maneuver IB(aSat)
Propagate aProp(aSat) {aSat.ElapsedDays = 1}
329
330
Reference Guide
ErrorModel
Used to specify measurement noise for simulation and estimation, and to apply or estimate measurement biases.
Description
An ErrorModel is assigned on the ErrorModels field of an instance of GroundStation to model
biases and noise, and optionally to estimate biases on each measurement type provided by the ground
station. An ErrorModel must be specified for each data type employed by each tracking station, but
a single instance of ErrorModel may be used by multiple ground stations.
The ErrorModel is used by both the simulator and the estimator. For a data simulation run, the
ErrorModel specifies the measurement type and noise employed when generating the simulated
measurement. A bias may optionally be applied to the simulated observations.
For an estimation run, the ErrorModel specifies the observation type, presumed observation noise,
and an optional bias to be applied to the observation. An observation bias may also be estimated by
adding the keyword Bias to the ErrorModel.SolveFors list. If the SolveFors list is empty, no bias
will be estimated. The SolveFors list is ignored by the simulator.
See Also GroundStation
Fields
Field
Description
Bias
The constant bias associated with the measurement. For simulations, this
bias is added to the measurement. As shown below, the units used depend
upon measurement type, ErrorModel.Type.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
BiasSigma
Real
Any Real number
set
0.0
Range_RU: RU, Doppler_HZ: Hz
script
Standard deviation of Bias. This field, which only has a function if
both (1) BatchEstimatorInv.UseInitialCovariance = true and (2) Bias
is a solve-for parameter, is used to constrain the estimated value of
Bias. As shown below, the units used depend upon measurement type,
ErrorModel.Type.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
Real
Real > 0
set
1e+70
Range_RU: RU, Doppler_HZ: Hz
script
331
Reference Guide
ErrorModel
Field
Description
NoiseSigma
One sigma value of Gaussian noise. For simulations, if Sim.AddNoise =
true, this noise is added to the measurements. For estimation, this value
is used to as part of the batch processing algorithms to calculate the measurement type weighting. As shown below, the units used depend upon
measurement type, ErrorModel.Type.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
SolveFors
List of fields to be solved for
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
Type
Real
Real > 0
set
103
Range_RU: RU, Doppler_HZ: Hz
script
StringArray
{} or {Bias}
set
{}
N/A
script
Measurement data type.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
Enumeration
Range_RU, Doppler_HZ
set
Range_RU
N/A
script
Remarks
Measurement Type Names
Currently, the measurement type names used to identify observation types in GMAT Measurement
Data (GMD) data files and on the TrackingFileSet.AddTrackingConfig object field are not the
same as those used to build measurement error models for those types. Use the following table as
a guide.
GMD File and
TrackingFileSet.AddTrackingConfig
Measurement Type Name
332
ErrorModel Measurement Type Name
DSNRange
Range_RU
Doppler
Doppler_HZ
ErrorModel
Reference Guide
Examples
This example shows how to create an ErrorModel for DSN range observations and illustrates
estimation of a range bias parameter.
%
Create an ErrorModel
Create ErrorModel Range_ErrorModel;
Range_ErrorModel.Type
Range_ErrorModel.NoiseSigma
Range_ErrorModel.Bias
Range_ErrorModel.SolveFors
%
=
=
=
=
'Range_RU';
11;
0.0;
{Bias};
Assign it to a ground station
Create GroundStation DSN;
DSN.ErrorModels = {Range_ErrorModel};
BeginMissionSequence;
333
334
Reference Guide
FileInterface
An interface to a data file
Description
The FileInterface resource is an interface to a data file that can be used to load mission data, like
Spacecraft state information and physical properties. Once an interface is established to a file, the
Set command can be used to load the data and apply it to a destination.
The following file formats are currently supported:
• TVHF_ASCII: ASCII format of the TCOPS Vector Hold File (TVHF), defined by the NASA
Goddard Space Flight Center Flight Dynamics Facility. This file contains spacecraft state and
physical information that can be transferred to a Spacecraft resource.
See Also: Set
Fields
Field
Description
Filename
Full path of the file to read. Relative paths are interpreted as relative to the directory
containing the GMAT executable. If the path is omitted, it is assumed to be “./”.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
Format
String
Valid file path
set
(None)
N/A
GUI, script
Format of the file to read. Currently, the only allowed format is “TVHF_ASCII”.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
Enumerated value
TVHF_ASCII
set
TVHF_ASCII
N/A
GUI, script
335
Reference Guide
FileInterface
GUI
The FileInterface GUI has two fields: a list of accepted options for Format (currently only
TVHF_ASCII), and an input box for Filename. Click Browse to the right of the Filename box
to interactively select a file.
Remarks
Each file format supported by the FileInterface resource exposes a set of keywords that can be
used to extract certain data elements. These keywords can be used in the Data option of the Set
command, as follows:
Set destination source (Data = {keyword[, keyword]})
If the 'All' keyword is used, those fields with a checkmark in the “All” column are selected.
TVHF_ASCII
Keyword
Source field
Description
CartesianState
Cartesian state elements (X, Y, Z, ✓
"CARTESIAN
COORDINATES" VX, VY, VZ)
Cr
"CSUBR"
Epoch
"EPOCH TIME Epoch of state vector
FOR ELEMENTS"
Coefficient of reflectivity
Limitations
The following limitations apply to the TVHF_ASCII format:
• Only the J2000 coordinate system is supported.
• Only the first record in a multiple-record file is loaded.
Examples
Read a TVHF file and use it to configure a spacecraft.
Create Spacecraft aSat
336
'All'
✓
✓
FileInterface
Reference Guide
Create FileInterface tvhf
tvhf.Filename = 'statevec.txt'
tvhf.Format = 'TVHF_ASCII'
BeginMissionSequence
Set aSat tvhf
337
338
Reference Guide
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: ChemicalTank, ChemicalThruster, Spacecraft, BeginFiniteBurn, EndFiniteBurn, Calculation Parameters
Fields
Field
Description
Thrusters
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 ChemicalThruster, if one has been created, with the FiniteBurn. This field cannot be modified in the Mission Sequence.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
Reference Array
A list of Thrusters created by user. Can
be a list of ChemicalThrusters or ElectricThrusters but you cannot mix chemical and electric thrusters.
set
No Default
N/A
GUI, script, or only one
339
Reference Guide
FiniteBurn
Field
Description
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.
Note: You can use GMAT scripting to covert from other representations
to Cartesian and then set the Cartesian format.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
Enumeration
Cartesian, Spherical
set
Cartesian
N/A
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 ChemicalThruster hardware resource with a created FiniteBurn. You must associate a specific ChemicalTank hardware
resource with the chosen ChemicalThruster. Finally, you must attach both the chosen Thrusters
and Tanks 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.
Using the scripting interface, one can assign multiple thrusters to a single FiniteBurn resource.
Interactions
Field
Spacecraft
source
340
Description
re- Must be created in order to apply any burn.
FiniteBurn
Reference Guide
Field
Thruster
source
Description
re- As discussed in the Remarks, every FiniteBurn resource must be associated
with at least one ChemicalThruster or ElectricThruster. Any thruster created in the resource tree can be incorporated into a FiniteBurn but thruster
types cannot be mixed.
ChemicalTank
resource
To perform a finite burn, a Tank must be attached to the Spacecraft. (A ChemicalTank is needed to provide pressure and temperature data used when modeling the thrust and specific impulse. A Tank is also needed if you want to
model mass depletion.)
BeginFiniteBurn After a FiniteBurn is created, to apply it in the mission sequence, a Beginand EndFinite- FiniteBurn and EndFiniteBurn command must be appended to the mission
Burn command tree.
Propagate com- In order to apply a non-zero finite burn, there must be a Propagate command
mand
between the BeginFiniteBurn and EndFiniteBurn commands.
Reporting FiniteBurn Parameters
GMAT now supports finite burn parameters that report the thrust component data for a finite burn.
The parameters include total thrust from all thrusters in the three coordinate directions, the total
acceleration from all thrusters in the three coordinate directions, and the total mass flow rate from all
thrusters. Currently, by default the total thrust and total acceleration parameters in the three coordinate directions are reported only in the J2000 system and do not support any other coordinate system
dependency. Furthermore, you can now also report out any thruster's individual parameters such as
thrust magnitude, Isp and mass flow rate. See the Calculation Parameters reference for definitions
of these finite burn and thruster specific parameters. Also see the Examples section for an example
that shows how to report the finite burn and individual thruster specific parameters to a report file.
Examples
Configure a chemical finite burn. Create a default Spacecraft and ChemicalTank Resource; Create
a default ChemicalThruster that allows for fuel depletion from the default ChemicalTank; Attach ChemicalTank and ChemicalThruster 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 ChemicalTank Resource
Create Spacecraft DefaultSC
Create ChemicalTank FuelTank1
% Create a default ChemicalThruster.
% the default ChemicalTank.
Create ChemicalThruster Thruster1
Thruster1.DecrementMass = true
Thruster1.Tank = {FuelTank1}
Allow for fuel depletion from
% Attach ChemicalTank and ChemicalThruster to the spacecraft
DefaultSC.Thrusters = {Thruster1}
DefaultSC.Tanks = {FuelTank1}
341
Reference Guide
FiniteBurn
% 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)
This example shows how to report finite burn parameters such as total acceleration (from all
thrusters), total thrust (from all thrusters) in the three coordinate directions. We also report total
mass flow rate from all thrusters. Additionally, individual thruster specific parameters such as thruster
mass flow rate, thrust magnitude and thruster Isp are also reported. Note that in the generated report, all finite burn and thruster parameters are reported as zeros when thrusters are not turned on.
Create Spacecraft aSat
Create ChemicalTank aFuelTank
Create ChemicalThruster aThruster
aThruster.DecrementMass = true
aThruster.Tank = {aFuelTank}
aThruster.C1 = 1000 % Constant Thrust
aThruster.K1 = 300 % Constant Isp
aSat.Thrusters = {aThruster}
aSat.Tanks = {aFuelTank}
Create ForceModel aFM
aFM.CentralBody = Earth
aFM.PointMasses = {Earth}
Create Propagator aProp
aProp.FM = aFM
Create FiniteBurn aFB
aFB.Thrusters = {aThruster}
Create ReportFile rf
rf.Add = {aSat.UTCGregorian, aFB.TotalAcceleration1, aFB.TotalAcceleration2, ...
aFB.TotalAcceleration3, aFB.TotalMassFlowRate, aFB.TotalThrust1, ...
342
FiniteBurn
Reference Guide
aFB.TotalThrust2, aFB.TotalThrust3, aSat.aThruster.MassFlowRate, ...
aSat.aThruster.ThrustMagnitude, aSat.aThruster.Isp}
BeginMissionSequence
Propagate aProp(aSat) {aSat.ElapsedSecs = 1000}
% Do a Finite-Burn for 1800 Secs
BeginFiniteBurn aFB(aSat)
Propagate aProp(aSat) {aSat.ElapsedSecs = 1800}
EndFiniteBurn aFB(aSat)
Propagate aProp(aSat) {aSat.ElapsedSecs = 1000}
343
344
Reference Guide
FminconOptimizer
The Sequential Quadratic Programming (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
Field
Description
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
Allowed Values
Access
Default Value
Units
Interfaces
DiffMinChange
String
Real Number > 0
Set
0.1
None
GUI, script
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
Allowed Values
Access
Default Value
Units
Interfaces
String
Real Number > 0
Set
1e-8
None
GUI, script
345
Reference Guide
FminconOptimizer
Field
Description
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
Allowed Values
Access
Default Value
Units
Interfaces
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
Allowed Values
Access
Default Value
Units
Interfaces
ReportFile
String
Any user-defined file name
Set
FminconOptimizerSQP1.data
None
GUI, script
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
Allowed Values
Access
Default Value
Units
Interfaces
346
String
Integer > 0
Set
25
None
GUI, script
Contains the path and file name of the report file.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
ReportStyle
String
Integer > 0
Set
1000
None
GUI, script
String
Normal, Concise, Verbose, Debug
Set
Normal
None
GUI, script
FminconOptimizer
Reference Guide
Field
Description
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
Allowed Values
Access
Default Value
Units
Interfaces
TolCon
Specifies the convergence tolerance on the constraint functions.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
TolFun
String
Real Number > 0
Set
1e-4
None
GUI, script
Specifies the convergence tolerance on the cost function value.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
TolX
Boolean
true, false
Set
true
None
GUI, script
String
Real Number > 0
Set
1e-4
None
GUI, script
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
Allowed Values
Access
Default Value
Units
Interfaces
String
Real Number > 0
Set
1e-4
None
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
347
Reference Guide
FminconOptimizer
(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}
348
FminconOptimizer
Reference Guide
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.
349
350
Reference Guide
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, Color
Fields
Field
Description
Add
Adds a list of Spacecraft to the Formation. The list cannot be empty.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
Resource array
array of spacecraft
set
empty list
N/A
GUI, script
GUI
To create a simple Formation and configure its Spacecraft, in the Resource Tree:
1.
2.
3.
4.
5.
Right-click the Spacecraft folder and select Add Spacecraft.
Right click the Formations folder and select Add Formation.
Double-click Formation1 to open its dialog box.
Click the right-arrow button twice to add DefaultSC and Spacecraft1 to Formation1.
Click Ok.
351
Reference Guide
Formation
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. You can only add a
spacecraft to a one formation, and you cannot add a formation to a formation. 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.
352
Formation
Reference Guide
Setting Colors On Spacecrafts In Formation Resource
If you want to set unique colors on spacecraft trajectories that are nested in the Formation resource,
then change colors through either the Spacecraft resource or the Propagate command. See the
Color documentation for discussion and examples on how to set unique colors on Spacecraft resource and Propagate command.
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}
353
354
Reference Guide
ChemicalTank
Model of a chemical fuel tank
Description
A ChemicalTank 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 ChemicalTank, you must first create the tank, and then attach it to the desired Spacecraft
and associate it with a ChemicalThruster as shown in the example below.
See Also ImpulsiveBurn,ChemicalThruster
Fields
Field
Description
AllowNegativeFuelMass
This field allows the ChemicalTank 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
Allowed Values
Access
Default Value
Units
Interfaces
FuelDensity
The density of the fuel.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
FuelMass
Boolean
true, false
set
false
N/A
GUI, script
Real
Real > 0
set, get
1260
kg/m^3
GUI, script
The mass of fuel in the tank.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
Real
Real > 0
set, get
756
kg
GUI, script
355
Reference Guide
ChemicalTank
Field
Description
Pressure
The pressure in the tank.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
PressureModel
The pressure model describes how pressure in the ChemicalTank
changes as fuel is depleted. This field cannot be modified in the
Mission Sequence.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
RefTemperature
Real
Real > -273.15 and |Real| > 0.01
set, get
20
C
GUI, script
The temperature of the fuel and ullage in the tank. GMAT currently assumes ullage and fuel are always at the same temperature.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
356
Enumeration
PressureRegulated, BlowDown
set
PressureRegulated
N/A
GUI, script
The temperature of the tank when fuel was loaded.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
Temperature
Real
Real > 0
set, get
1500
kPa
GUI, script
Real
Real > -273.15
set, get
20
C
GUI, script
ChemicalTank
Reference Guide
Field
Description
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
Allowed Values
Access
Default Value
Units
Interfaces
Real
Real > 0 such that calculated fuel volume
is < input tank Volume.
set, get
0.75
m^3
GUI, script
GUI
The ChemicalTank 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 ChemicalTank
dialog box is shown below.
The ChemicalThruster resource is closely related to the ChemicalTank resource and thus, we also
discuss it here. The ChemicalThruster 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 ChemicalThruster dialog box is shown below.
357
Reference Guide
ChemicalTank
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 ChemicalTank as shown below.
358
ChemicalTank
Reference Guide
Thus far, we have created both a ChemicalTank and a ChemicalThruster, and we have associated
a ChemicalTank with our ChemicalThruster. We are not done yet. We must tell GMAT that we
want to attach both the ChemicalTank and the ChemicalThruster 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.
359
Reference Guide
ChemicalTank
Next, select the desired ChemicalTank and use the right arrow button to attach the ChemicalTank
to the spacecraft. Then, click the Apply button as shown below.
360
ChemicalTank
Reference Guide
Similarly, to attach a ChemicalThruster 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.
361
Reference Guide
ChemicalTank
Remarks
Use of ChemicalTank Resource in Conjunction with Maneuvers
A ChemicalTank 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 ChemicalTank with it. The actual impulsive maneuver is implemented using the Maneuver command. See the Maneuver command documentation for worked examples on how the ChemicalTank resource is used in conjunction with impulsive maneuvers.
To implement a finite maneuver, you must first create both a ChemicalThruster and a FiniteBurn
resource. You must also associate a ChemicalTank with the ChemicalThruster 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 ChemicalTank resource is used
in conjunction with finite maneuvers.
Behavior When Configuring Tank and Attached Tank Properties
Create a default ChemicalTank and attach it to a Spacecraft and ChemicalThruster.
%
362
Create the ChemicalTank Resource
ChemicalTank
Reference Guide
Create ChemicalTank 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 ChemicalThruster and assign it a ChemicalTank
Create ChemicalThruster aThruster
aThruster.Tank = {aTank}
% Add the ChemicalTank and ChemicalThruster 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 ChemicalTank 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 ChemicalTank and ChemicalThruster 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.
363
Reference Guide
ChemicalTank
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 ChemicalTank and attach it to a Spacecraft and ChemicalThruster.
% Create the Fuel Tank Resource
Create ChemicalTank 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 ChemicalThruster and assign it a ChemicalTank
Create ChemicalThruster aThruster
aThruster.Tank = {aTank}
% Add the ChemicalTank and ChemicalThruster to a Spacecraft
Create Spacecraft aSpacecraft
aSpacecraft.Tanks = {aTank}
aSpacecraft.Thrusters = {aThruster}
BeginMissionSequence
364
Reference Guide
GMATFunction
Declaration of a GMAT function
Description
The GmatFunction resource declares a new GMAT function or can be used to load-in a preexisting GMAT function. This function can be called in the Mission Sequence through GMAT's
CallGmatFunction command. See the CallGmatFunction reference for details.
Through this GMAT function, data can be passed in the function as input and received as output.
Data that is passed into the function as input or received from the function as output can also be
declared as global. See the Global reference for more details. See also the Remarks and Examples
sections for detailed discussion on GMAT functions and how to use them.
See Also: CallGmatFunction, Global
Fields
Field
Description
FunctionPath
Allows the user to define a valid function path. In the GUI, the FunctionPath field
is activated after editing the function and then clicking on the function's Save As
button. The path of the function can be defined as either absolute or relative.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
String
Valid file path. The path can be either absolute or relative. In
the Script mode, if this field is not used at all, then default
location of functions is GMAT's ...\userfunctions\gmat\ directory
set
User-defined
N/A
GUI, script
GUI
In the GUI, a new GmatFunction resource is created as follows:
1. In the Resources Tree, right click on the Functions folder, select Add -> GMAT Function
-> New
2. In the New GMAT function dialog box, type the desired name of your function.
365
Reference Guide
GMATFunction
The GmatFunction resource's GUI window is very simple. When a new GMAT function is created
through the GUI, the FunctionPath field is defined by first editing the function and then clicking
on the Save As button. This lets you graphically define the path.
Remarks
Input and Output Arguments
Arguments can be passed into a GMAT function as input and returned from a GMAT function as
output. You can pass GMAT objects as input to a function and receive entire objects as output from
the function. If a given GMAT object is not declared as global in both the main script and in the
function, then all objects that are passed into or received as output from the function are considered
to be local to that function and the main script.
In GMAT, you can use CallGmatFunction command to pass GMAT objects as input arguments
and receive objects as output from the function. In general, any objects in GMAT's Resources tree
can be passed as input to the function. Most common objects that a user is likely to pass as input to
the function are objects that are related to propagating a spacecraft, performing differential correction (DC) in a targeter, implementing optimization in an optimizer loop, user-defined variables/arrays/strings or subscribers that are used to draw or report parameters. Most common objects that
are likely to be passed as output arguments from the function maybe a Spacecraft resource or userdefined objects such as Variables, Arrays or Strings.
Below is a list of allowed objects that can be passed as input and output to and from the function.
Also see Examples section that show two distinct methods in two separate examples of how to pass
local objects as inputs to the function, perform an operation inside the function, then receive local
objects as outputs from the function.
366
GMATFunction
Reference Guide
The input arguments can be any of the following types:
• Any resource objects (e.g. Spacecraft, Propagator, DC, Optimizers, Impulsive or FiniteBurns)
• resource parameter of real number type (e.g. Spacecraft.X)
• resource parameter of string type (e.g. Spacecraft.UTCGregorian)
• Array, String, or Variable resource
The output arguments can be any of the following types:
•
•
•
•
Resource object like Spacecraft
resource parameter of real number type (e.g. Spacecraft.X)
resource parameter of string type (e.g. Spacecraft.UTCGregorian)
Array, String, or Variable resource
Global Spacecraft, Subscribers and Other Objects
In GMAT, objects can be declared as global by using the Global command in the Mission tree. All
default objects present in GMAT's Resources tree or any new user-defined resources can be declared
as global. Currently any default or new user-defined coordinate systems, SolarSystemBarycenter,
SolarSystem, default or new user-defined propagators are automatic global objects and not needed
to be specifically declared as global via the Global command.
Often times, there will be cases when you will propagate a spacecraft both in the main script and
from inside the GMAT function. Additionally users may want to report and/or plot spacecraft's
trajectory, parameters, variables, arrays and strings to same subscribers both from the main script
and/or solely from inside the function. If you want to report and plot continuous set of data to any
of the five subscribers (i.e. OrbitView, GroundTrackPlot, XYPlot, ReportFile, EphemerisFile),
then always declare your Spacecraft object and subscriber objects as global both in the main script
and inside the function. Abiding by this rule draws plots, reports and ephemeris files correctly and
flow of data will be reported continuously to all the subscribers.
In general, a good scripting practice is that objects that have been declared global don't need to be
sent as input or output arguments to and from the function. For example, if Spacecraft, all subscriber
objects or objects that are used to perform propagation, targeting or optimization have already been
declared global, then you don't to be redundant and send those global objects again as input or
receive them as output from the function. Having said that, GMAT does allow globally declared
objects such as Spacecraft, global variables/arrays/strings to be passed as input/output argument
to and from the function. Globally declared objects such as spacecraft, variables/arrays/strings can
be plotted or reported interchangeably both from the main script and inside the function to globally
declared subscribers.
See Examples section that shows three examples of how to declare spacecraft, all five subscribers and
variables/arrays as global in both the main script and inside the function. As you run the examples,
notice that the flow of data reported to all five subscribers is continuous.
Using GMAT Functions in an Assignment Command
GMAT allows you to use simple GMAT functions in the main script in an assignment command
mode. Below example snippet shows how to use simple GMAT functions in mathematical state367
Reference Guide
GMATFunction
ments. Note that in the below snippet, function path to GMAT function's FunctionPath field
was not specifically defined. Whenever the FunctionPath field is not defined in the script mode,
then preferred default path of these functions is in the following directory where GMAT was installed: ..GMAT\userfunctions\gmat\
%%Using a GMAT function in a mathematical statement
Create ReportFile rf
Create GmatFunction Math_GmatPi Math_GmatSin
Create GmatFunction Math_GmatAtan2 Math_GmatInv
Create Variable x y z pi in
Create Array A[2,2] B[2,2]
BeginMissionSequence
A(1,1)
A(1,2)
A(2,1)
A(2,2)
=
=
=
=
1
3
4
2
% no inputs into the function
pi = Math_GmatPi * 2
Report rf pi
% one input into the function
[pi] = Math_GmatPi
in = pi/4
x = Math_GmatSin(in) - 15
Report rf x
% two inputs:
in = 0.5
y = Math_GmatAtan2(in, x)^2
Report rf y
% array input/output:
B = Math_GmatInv(A)'
Report rf B
%%%% Math_GmatPi Function begins below:
function [pi] = Math_GmatPi
Create Variable pi
BeginMissionSequence
pi = acos(-1)
368
GMATFunction
Reference Guide
%%%% Math_GmatSin Function begins below:
function [y] = Math_GmatSin(x)
Create Variable y
BeginMissionSequence
y = sin(x)
%%%% Math_GmatAtan2 Function begins below:
function [z] = Math_GmatAtan2(y, x)
Create Variable z
BeginMissionSequence
z = atan2(y, x)
%%%% Math_GmatInv Function begins below:
function [B] = Math_GmatInv(A)
Create Array B[2,2]
BeginMissionSequence
B = inv(A)
Examples
Method 1 of how to pass local objects into the function and receiving local objects as the output
from the function. Pass local spacecraft, other local objects into the function, perform hohmann
targeting inside the function, receive updated local spacecraft, local variables as output and finally
report them to local subscribers in the main script. Since the spacecraft and all five subscribers were
only local objects (i.e. not declared as global), hence notice that all subscribers begin to draw and
report data once the updated spacecraft is returned back and propagated in the main script.
Create Spacecraft aSat
Create ForceModel aFM
aFM.CentralBody = Earth
aFM.PointMasses = {Earth}
Create Propagator aProp
aProp.FM = aFM
Create ImpulsiveBurn TOI
Create ImpulsiveBurn GOI
Create DifferentialCorrector DC
Create OrbitView anOrbitView
anOrbitView.SolverIterations = Current
369
Reference Guide
GMATFunction
anOrbitView.Add = {aSat, Earth}
Create GroundTrackPlot GroundTrackPlot1
GroundTrackPlot1.Add = {aSat}
GroundTrackPlot1.CentralBody = Earth
Create XYPlot XYPlot1
XYPlot1.XVariable = aSat.ElapsedDays
XYPlot1.YVariables = {aSat.EarthMJ2000Eq.X}
Create ReportFile rf
rf.Add = {aSat.UTCGregorian, aSat.EarthMJ2000Eq.X, ...
aSat.EarthMJ2000Eq.Y, aSat.EarthMJ2000Eq.Z, ...
aSat.EarthMJ2000Eq.VX, aSat.EarthMJ2000Eq.VY, aSat.EarthMJ2000Eq.VZ}
Create ReportFile rf2
rf2.WriteHeaders = false
Create EphemerisFile anEphemerisFile
GMAT anEphemerisFile.Spacecraft = aSat
Create GmatFunction Targeter_Inside_Function
Targeter_Inside_Function.FunctionPath = ...
'C:\Users\rqureshi\Desktop\Targeter_Inside_Function.gmf'
Create Variable DV1 DV2
BeginMissionSequence;
% Pass local S/C, local objects into function and receive back
% updated local S/C and local variables:
'Hohmann Transfer'[DV1, DV2, aSat] ...
= Targeter_Inside_Function(aSat, aProp, TOI, GOI, DC)
TOI.Element1 = DV1
GOI.Element1 = DV2
% Report updated S/C:
Report rf2 aSat.UTCModJulian aSat.UTCGregorian aSat.X aSat.Y aSat.Z ...
aSat.VX aSat.VY aSat.VZ TOI.Element1 GOI.Element1
Propagate 'Prop one day' aProp(aSat) {aSat.ElapsedDays = 1.0}
Report rf2 aSat.UTCModJulian aSat.UTCGregorian aSat.X aSat.Y aSat.Z ...
aSat.VX aSat.VY aSat.VZ
%%%%%%%%%%% Function begins below:
370
GMATFunction
Reference Guide
function [dv1, dv2, aSat] = Targeter_Inside_Function(aSat, aProp, TOI, GOI, DC)
% Create local S/C, local variables:
Create Spacecraft aSat
Create Variable dv1 dv2
BeginMissionSequence
Propagate 'Propagate to Periapsis' aProp(aSat) {aSat.Earth.Periapsis}
Target 'Hohmann Transfer' DC {SolveMode = Solve, ExitMode = SaveAndContinue}
Vary 'Vary TOI' DC(TOI.Element1 = 1.0, {Perturbation = 0.0001, ...
Lower = 0.0, Upper = 3.14159, MaxStep = 0.5})
Maneuver 'Perform TOI' TOI(aSat)
Propagate 'Prop to Apoapsis' aProp(aSat) {aSat.Earth.Apoapsis}
Achieve 'Achieve RMAG = 42165' DC(aSat.Earth.RMAG = 42165)
Vary 'Vary GOI' DC(GOI.Element1 = 1.0, {Perturbation = 0.0001, ...
Lower = 0.0, Upper = 3.14159, MaxStep = 0.2})
Maneuver 'Perform GOI' GOI(aSat)
Achieve 'Achieve ECC = 0.005' DC(aSat.Earth.ECC = 0.005)
EndTarget
dv1 = TOI.Element1
dv2 = GOI.Element1
Method 2 of how to pass local objects into the function and receiving local objects as the output
from the function. In this method, notice that we now only pass local spacecraft as input to the
function. Instead of passing additional local objects into the function, we now create those required
local objects inside the function itself. Similar to method 1, we perform hohmann targeting inside
the function, then send updated spacecraft and variables back to the main script as output from the
function. Finally updated spacecraft is propagated for one day in main script and reported by all
subscribers. Since the spacecraft and all five subscribers were only local objects (i.e. not declared as
global), hence notice that all subscribers begin to draw and report data once the updated spacecraft
begins propagation in the main script.
Create Spacecraft aSat
Create ForceModel aFM
aFM.CentralBody = Earth
aFM.PointMasses = {Earth}
Create Propagator aProp
aProp.FM = aFM
Create ImpulsiveBurn TOI
Create ImpulsiveBurn GOI
Create DifferentialCorrector DC
371
Reference Guide
GMATFunction
Create OrbitView anOrbitView
anOrbitView.SolverIterations = Current
anOrbitView.Add = {aSat, Earth}
Create GroundTrackPlot GroundTrackPlot1
GroundTrackPlot1.Add = {aSat}
GroundTrackPlot1.CentralBody = Earth
Create XYPlot XYPlot1
XYPlot1.XVariable = aSat.ElapsedDays
XYPlot1.YVariables = {aSat.EarthMJ2000Eq.X}
Create ReportFile rf
rf.Add = {aSat.UTCGregorian, aSat.EarthMJ2000Eq.X, ...
aSat.EarthMJ2000Eq.Y, aSat.EarthMJ2000Eq.Z, ...
aSat.EarthMJ2000Eq.VX, aSat.EarthMJ2000Eq.VY, aSat.EarthMJ2000Eq.VZ}
Create ReportFile rf2
rf2.WriteHeaders = false
Create EphemerisFile anEphemerisFile
GMAT anEphemerisFile.Spacecraft = aSat
Create GmatFunction Targeter_Inside_Function
Targeter_Inside_Function.FunctionPath = ...
'C:\Users\rqureshi\Desktop\Targeter_Inside_Function.gmf'
Create Variable DV1 DV2
BeginMissionSequence;
% Pass only local S/C into the function and receive back
% updated local S/C and local variables:
'Hohmann Transfer'[DV1, DV2, aSat] ...
= Targeter_Inside_Function(aSat)
TOI.Element1 = DV1
GOI.Element1 = DV2
% Report updated S/C:
Report rf2 aSat.UTCModJulian aSat.UTCGregorian aSat.X aSat.Y aSat.Z ...
aSat.VX aSat.VY aSat.VZ TOI.Element1 GOI.Element1
Propagate 'Prop one day' aProp(aSat) {aSat.ElapsedDays = 1.0}
Report rf2 aSat.UTCModJulian aSat.UTCGregorian aSat.X aSat.Y aSat.Z ...
aSat.VX aSat.VY aSat.VZ
372
GMATFunction
Reference Guide
%%%%%%%%%%% Function begins below:
function [dv1, dv2, aSat] = Targeter_Inside_Function(aSat)
% Create local S/C:
Create Spacecraft aSat
% Create local objects that are used to do targeting:
Create ForceModel aFM
aFM.CentralBody = Earth
aFM.PointMasses = {Earth}
Create Propagator aProp
aProp.FM = aFM
Create ImpulsiveBurn TOI
Create ImpulsiveBurn GOI
Create DifferentialCorrector DC
% Create local variables:
Create Variable dv1 dv2
BeginMissionSequence
Propagate 'Propagate to Periapsis' aProp(aSat) {aSat.Earth.Periapsis}
Target 'Hohmann Transfer' DC {SolveMode = Solve, ExitMode = SaveAndContinue}
Vary 'Vary TOI' DC(TOI.Element1 = 1.0, {Perturbation = 0.0001, ...
Lower = 0.0, Upper = 3.14159, MaxStep = 0.5})
Maneuver 'Perform TOI' TOI(aSat)
Propagate 'Prop to Apoapsis' aProp(aSat) {aSat.Earth.Apoapsis}
Achieve 'Achieve RMAG = 42165' DC(aSat.Earth.RMAG = 42165)
Vary 'Vary GOI' DC(GOI.Element1 = 1.0, {Perturbation = 0.0001, ...
Lower = 0.0, Upper = 3.14159, MaxStep = 0.2})
Maneuver 'Perform GOI' GOI(aSat)
Achieve 'Achieve ECC = 0.005' DC(aSat.Earth.ECC = 0.005)
EndTarget
dv1 = TOI.Element1
dv2 = GOI.Element1
In this example, we declare spacecraft, all subscribers and other objects as global in both main script
and in function. Propagate inside the function, perform targeting inside function, and report local
variables, global spacecraft state and global variable (DV1, DV2) to global reportfile. Next, we continue to propagate in the main script and continue to report spacecraft state to global reportfile in the
main script. After running this example, pay special attention to all subscribers. Note that spacecraft
trajectory is plotted continuously on three plotting subscribers and data is reported continuously as
well to both reportfiles and ephemerisfile.
373
Reference Guide
GMATFunction
Create Spacecraft aSat
Create ForceModel aFM
aFM.CentralBody = Earth
aFM.PointMasses = {Earth}
Create Propagator aProp
aProp.FM = aFM
Create ImpulsiveBurn TOI
Create ImpulsiveBurn GOI
Create DifferentialCorrector DC
Create OrbitView anOrbitView
anOrbitView.SolverIterations = Current
anOrbitView.Add = {aSat, Earth}
Create GroundTrackPlot GroundTrackPlot1
GroundTrackPlot1.Add = {aSat}
GroundTrackPlot1.CentralBody = Earth
Create XYPlot XYPlot1
XYPlot1.XVariable = aSat.ElapsedDays
XYPlot1.YVariables = {aSat.EarthMJ2000Eq.X}
Create ReportFile rf
rf.Add = {aSat.UTCGregorian, aSat.EarthMJ2000Eq.X, ...
aSat.EarthMJ2000Eq.Y, aSat.EarthMJ2000Eq.Z, ...
aSat.EarthMJ2000Eq.VX, aSat.EarthMJ2000Eq.VY, aSat.EarthMJ2000Eq.VZ}
Create ReportFile rf2
rf2.WriteHeaders = false
Create EphemerisFile anEphemerisFile
GMAT anEphemerisFile.Spacecraft = aSat
Create GmatFunction Global_Subscribers
Global_Subscribers.FunctionPath = ...
'C:\Users\rqureshi\Desktop\Global_Subscribers.gmf'
Create Variable DV1 DV2
BeginMissionSequence;
% Declare aSat, Subscribers and other objects as Global:
Global aSat
Global aFM TOI GOI DC %aProp is global by default.
Global anOrbitView GroundTrackPlot1 XYPlot1 rf rf2 anEphemerisFile
374
GMATFunction
Reference Guide
Global DV1 DV2
Report rf2 aSat.UTCGregorian aSat.UTCModJulian aSat.X aSat.Y aSat.Z ...
aSat.VX aSat.VY aSat.VZ
% Call function:
Global_Subscribers()
% Report updated Global S/C, TOI and GOI:
Report rf2 aSat.UTCGregorian aSat.UTCModJulian aSat.X aSat.Y aSat.Z ...
aSat.VX aSat.VY aSat.VZ TOI.Element1 GOI.Element1
Propagate 'Prop one more day' aProp(aSat) {aSat.ElapsedDays = 1.0}
Report rf2 aSat.UTCGregorian aSat.UTCModJulian aSat.X aSat.Y aSat.Z ...
aSat.VX aSat.VY aSat.VZ
% Report Global DV1 and DV2 to global 'rf2' in main script:
Report rf2 DV1 DV2
%%%%%%%%%%% Function begins below:
function Global_Subscribers()
% Create Local variables, string:
Create Variable sc_epoch x y z vx vy vz dv1 dv2;
Create String utc_epoch
Global
Global
Global
Global
aSat
aFM TOI GOI DC
anOrbitView GroundTrackPlot1 XYPlot1 rf rf2 anEphemerisFile
DV1 DV2
BeginMissionSequence
Propagate 'Propagate to Periapsis' aProp(aSat) {aSat.Earth.Periapsis}
Target 'Hohmann Transfer' DC {SolveMode = Solve, ExitMode = SaveAndContinue}
Vary 'Vary TOI' DC(TOI.Element1 = 1.0, {Perturbation = 0.0001, ...
Lower = 0.0, Upper = 3.14159, MaxStep = 0.5})
Maneuver 'Perform TOI' TOI(aSat)
Propagate 'Prop to Apoapsis' aProp(aSat) {aSat.Earth.Apoapsis}
Achieve 'Achieve RMAG = 42165' DC(aSat.Earth.RMAG = 42165)
Vary 'Vary GOI' DC(GOI.Element1 = 1.0, {Perturbation = 0.0001, ...
Lower = 0.0, Upper = 3.14159, MaxStep = 0.2})
Maneuver 'Perform GOI' GOI(aSat)
Achieve 'Achieve ECC = 0.005' DC(aSat.Earth.ECC = 0.005)
EndTarget
375
Reference Guide
GMATFunction
sc_epoch = aSat.UTCModJulian
utc_epoch = aSat.UTCGregorian
x = aSat.X
y = aSat.Y
z = aSat.Z
vx = aSat.VX
vy = aSat.VY
vz = aSat.VZ
dv1 = TOI.Element1
dv2 = GOI.Element1
% Report local variables/strings to Global reportfile 'rf2':
Report rf2 utc_epoch sc_epoch x y z vx vy vz dv1 dv2
Propagate 'Prop one Day Inside Function' aProp(aSat) {aSat.ElapsedDays = 1.0}
% Report Global aSat state to global 'rf2':
Report rf2 aSat.UTCGregorian aSat.UTCModJulian
aSat.VY aSat.VZ TOI.Element1 GOI.Element1
aSat.X aSat.Y aSat.Z aSat.VX ...
% Report Global variables DV1 and DV2 to global 'rf2' in main script:
DV1 = TOI.Element1
DV2 = TOI.Element1
Just as previous example, we declare spacecraft, all subscribers and other objects as global in both
main script and in function. This time GMAT function is nested inside control logic statements like
While and If-EndIf. LEO station-keeping is performed inside the function. As the example will be
running, pay special attention to all subscribers. Note that spacecraft trajectory is plotted continuously on three plotting subscribers and data is reported continuously as well to both reportfiles and
ephemerisfile.
Create Spacecraft LEOsat
LEOsat.DisplayStateType = Keplerian
LEOsat.SMA = 6733.989999999996
LEOsat.ECC = 0.0004329999999984123
LEOsat.INC = 34.98399999999998
LEOsat.RAAN = 274.742
LEOsat.AOP = 287.8049999999732
LEOsat.TA = 294.0690000000269
Create ForceModel LEOprop_ForceModel
LEOprop_ForceModel.CentralBody = Earth
LEOprop_ForceModel.PrimaryBodies = {Earth}
LEOprop_ForceModel.PointMasses = {Luna, Sun}
LEOprop_ForceModel.SRP = On
LEOprop_ForceModel.GravityField.Earth.Degree = 4
LEOprop_ForceModel.GravityField.Earth.Order = 4
376
GMATFunction
Reference Guide
LEOprop_ForceModel.GravityField.Earth.PotentialFile = 'JGM2.cof'
LEOprop_ForceModel.Drag.AtmosphereModel = JacchiaRoberts
LEOprop_ForceModel.Drag.F107 = 150
LEOprop_ForceModel.Drag.F107A = 150
Create Propagator LEOprop
GMAT LEOprop.FM = LEOprop_ForceModel
Create ImpulsiveBurn TCM1
Create ImpulsiveBurn TCM2
Create DifferentialCorrector DC
Create OrbitView DefaultOrbitView
DefaultOrbitView.Add = {LEOsat, Earth}
Create XYPlot XYPlot1
GMAT XYPlot1.XVariable = LEOsat.A1ModJulian
GMAT XYPlot1.YVariables = {LEOsat.Earth.Altitude}
Create GroundTrackPlot GroundTrackPlot1
GroundTrackPlot1.Add = {LEOsat}
Create ReportFile rf
Create ReportFile rf2
rf2.Add = {LEOsat.UTCModJulian, LEOsat.Earth.Altitude, ...
LEOsat.Earth.RMAG, LEOsat.Earth.ECC}
Create EphemerisFile anEphemerisFile
GMAT anEphemerisFile.Spacecraft = LEOsat
Create GmatFunction TargetLEOStationKeeping
TargetLEOStationKeeping.FunctionPath = ...
'C:\Users\rqureshi\Desktop\TargetLEOStationKeeping.gmf'
Create Variable desiredRMAG desiredECC X Y Z
BeginMissionSequence
desiredRMAG = 6737
desiredECC = 0.00005
% Declare LEOsat, Subscribers and other objects as Global:
Global LEOsat
Global DC TCM1 TCM2 LEOprop_ForceModel
Global DefaultOrbitView XYPlot1 GroundTrackPlot1
Global rf rf2 anEphemerisFile
377
Reference Guide
GMATFunction
While 'While ElapsedDays < 10' LEOsat.ElapsedDays < 10.0
Propagate 'Prop One Step' LEOprop(LEOsat)
If 'If Alt < Threshold' LEOsat.Earth.Altitude < 342
Propagate 'Prop To Periapsis' LEOprop(LEOsat) {LEOsat.Periapsis}
% Call function to implement SK. Pass local variables as input:
TargetLEOStationKeeping(desiredRMAG,desiredECC)
EndIf
EndWhile
Report rf LEOsat.UTCGregorian LEOsat.UTCModJulian LEOsat.X ...
LEOsat.Y LEOsat.Z LEOsat.Earth.Altitude LEOsat.Earth.ECC
%%%%%%%%%%% Function begins below:
function TargetLEOStationKeeping(desiredRMAG,desiredECC)
BeginMissionSequence
Global
Global
Global
Global
LEOsat
DC TCM1 TCM2 LEOprop_ForceModel
DefaultOrbitView XYPlot1 GroundTrackPlot1
rf rf2 anEphemerisFile
Target 'Raise Orbit' DC {SolveMode = Solve, ExitMode = DiscardAndContinue}
Vary 'Vary TCM1.V' DC(TCM1.Element1 = 0.002, {Perturbation = 0.0001, ...
Lower = -9.999999e300, Upper = 9.999999e300, MaxStep = 0.05})
Maneuver 'Apply TCM1' TCM1(LEOsat);
Propagate 'Prop to Apoapsis' LEOprop(LEOsat) {LEOsat.Apoapsis}
Achieve 'Achieve RMAG' DC(LEOsat.RMAG = desiredRMAG, {Tolerance = 0.1})
Vary 'Vary TCM2.V' DC(TCM2.Element1 = 1e-005, {Perturbation = 0.00005, ...
Lower = -9.999999e300, Upper = 9.999999e300, MaxStep = 0.05})
Maneuver 'Apply TCM2' TCM2(LEOsat);
Achieve 'Achieve ECC' DC(LEOsat.Earth.ECC = desiredECC)
EndTarget
In this example, all arrays, string and a single subscriber are declared global both in main script and
inside function. Note that global arrays are passed into the function, cross products are computed
and computed global arrays (v5, v6) are sent back to the main script. Also note that global arrays,
string are reported to global report file in both main script and inside the function.
Create ReportFile rf
378
GMATFunction
Reference Guide
rf.WriteHeaders = false
Create GmatFunction cross3by1;
GMAT cross3by1.FunctionPath = ...
'C:\Users\rqureshi\Desktop\cross3by1.gmf'
Create Array v1[3,1] v2[3,1] v3[3,1] ...
v4[3,1] v5[3,1] v6[3,1]
Create String tempstring
BeginMissionSequence
% Declare Arrays, string and subscriber as global:
Global v1 v2 v3 v4 v5 v6 tempstring rf
v1(1,1)
v1(2,1)
v1(3,1)
v2(1,1)
v2(2,1)
v2(3,1)
v3(1,1)
v3(2,1)
v3(3,1)
v4(1,1)
v4(2,1)
v4(3,1)
=
=
=
=
=
=
=
=
=
=
=
=
1
2
3
4
5
6
8
9
10
10
11
12
% Report global arrays/string to global 'rf':
Report rf v1 v2 v3 v4
tempstring = '--------------------'
Report rf tempstring
% Call function. Pass in Global arrays
% Receive global arrays in return:
GMAT [v5, v6] = cross3by1(v1, v2, v3, v4)
% Report global output to global 'rf':
Report rf v5 v6
tempstring = '--------------------'
Report rf tempstring
%%%%%%%%%%% Function begins below:
function [v5, v6] = cross3by1(vector1,vector2, vector3, vector4)
BeginMissionSequence
379
Reference Guide
GMATFunction
Global v1 v2 v3 v4 v5 v6
tempstring rf
v5(1,1) = vector1(2,1)*vector2(3,1) - vector1(3,1)*vector2(2,1)
v5(2,1) = -(vector1(1,1)*vector2(3,1) - vector1(3,1)*vector2(1,1))
v5(3,1) = vector1(1,1)*vector2(2,1) - vector1(2,1)*vector2(1,1)
v6(1,1) = vector3(2,1)*vector4(3,1) - vector3(3,1)*vector4(2,1)
v6(2,1) = -(vector3(1,1)*vector4(3,1) - vector3(3,1)*vector4(1,1))
v6(3,1) = vector3(1,1)*vector4(2,1) - vector3(2,1)*vector4(1,1)
v1
v2
v3
v4
=
=
=
=
v1 + 1
v2*2
v3/2
v4 + v4
% Continue to report global arrays/string to global 'rf':
Report rf v1 v2 v3 v4
tempstring = '--------------------'
Report rf tempstring
380
Reference Guide
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: ContactLocator, CoordinateSystem, Color
Fields
Field
Description
AddHardware
List of all Transmitter, Receiver, and Antenna hardware used by ground
station
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
Altitude
The altitude of the station with respect to the HorizonReference.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
CentralBody
Object Array
Each element in the list has to be a valid Transmitter, Receiver, or Antenna
set
None
N/A
script
Real
-∞ < Real < ∞
set
0
km
GUI, script
The central body of the GroundStation.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
String
Earth. (Ground stations are currenly only supported with respect to Earth)
set
Earth
N/A
GUI, script
381
Reference Guide
GroundStation
Field
Description
DataSource
Source of where to get Temperature, Pressure, Humidity, and MinimumElevationAngle. If the value is Constant, then the values of these
parameters, as set in the GroundStation resource, remain constant for
all relevant measurements. Currently, the value of Constant is the only allowed value.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
ErrorModels
User-defined list of ErrorModel objects that describe the measurement
error models used for this GroundStation.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
HorizonReference
String
Sphere, Ellipsoid
set
Sphere
N/A
GUI, script
Humidity at ground station used to calculate tropospheric correction.
GMAT only uses this value if DataSource is set to Constant.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
382
StringList
Any valid user-defined ErrorModel resource
set
None
N/A
script
The system used for the horizon. Sphere is equivalent to Geocentric, Ellipsoid is equivalent to Geodetic.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
Humidity
Enumeration
Constant
set
Constant
N/A
script
Real
0.0 <= Real <=100.0
set, get
55
percentage
script
GroundStation
Reference Guide
Field
Description
Id
Id of the GroundStation used in simulation and estimation
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
IonosphereModel
Specification of ionospheric model used in the light time calculations.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
Latitude
Enumeration
'None', 'IRI2007'
set
'None'
N/A
script
The latitude of the station with respect to HorizonReference.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
Location1
String
May contain letters, integers, dashes, underscores
set,
StationId
N/A
GUI, script
Real
-90 < Real < 90
set
0
deg.
GUI, script
The first component of the GroundStation location. When StateType is
Cartesian, Location1 is the x-component of station location in the bodyfixed system. When StateType is Spherical or Elliposoid, Location1 is
the Longitude (deg.) of the GroundStation.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
Real
-∞ < Real < ∞ for Cartesian, See Longitude,
Latitude, Altitude for others.
set
6378.1363
see description
GUI, script
383
Reference Guide
GroundStation
Field
Description
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
Allowed Values
Access
Default Value
Units
Interfaces
Location3
The third component of the GroundStation location. When StateType is
Cartesian, Location3 is the z-component of station location in the bodyfixed system. When StateType is Spherical or Elliposoid, Location3 is
the height (km) of the GroundStation above the reference shape.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
Longitude
Real
value >=0
set
0
deg.
GUI, script
Minimum elevation angle constraint for use with ContactLocator. For
navigation related processing, this is minimum elevation angle for signal
transmitted from spacecraft to ground station. During simulation, this is
the minimum elevation angle required in order for data to be output. During estimation, this is the minimum elevation angle required for data to be
used to calculate an estimate. GMAT only uses this value if DataSource
is set to Constant.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
384
Reals
-∞ < Real < ∞ for Cartesian, See Longitude,
Latitude, Altitude for others.
set,
0
see description
GUI, script
The longitude of the station.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
MinimumElevationAngle
Real
-∞ < Real < ∞ for Cartesian, See Longitude,
Latitude, Altitude for others.
set
0
see description
GUI, script
Real
-90 ≤ MinimumElevationAngle ≤ 90
set
7
deg
GUI, script
GroundStation
Reference Guide
Field
Description
OrbitColor
Allows you to select available colors for a user-defined GroundStation. The GroundStation object is drawn on a spacecraft's ground
track plot created by GroundTrackPlot 2D graphics display resource.
The colors can be identified through a string or an integer array.
For example: Setting groundstation's color to red can be done in
following two ways: GroundStation.OrbitColor = Red or
GroundStation.OrbitColor = [255 0 0]. This field can be modified in the Mission Sequence as well.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
Pressure
Air pressure at ground station used to calculate tropospheric correction.
GMAT only uses this value if DataSource is set to Constant.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
StateType
Integer Array or String
Any color available from the Orbit Color Picker in
GUI. Valid predefined color name or RGB triplet
value between 0 and 255.
set
Thistle
N/A
GUI, script
Real
Real >0.0
set, get
1013.5
hPa
script
The type of state used to define the location of the ground station. For
example, Cartesian or Ellipsoid.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
String
Cartesian, Spherical, Ellipsoid
set
Cartesian
N/A
GUI, script
385
Reference Guide
GroundStation
Field
Description
TargetColor
Allows you to select available colors for a user-defined GroundStation
object during iterative processes such as Differential Correction or Optimization. The target color can be identified through a string or an integer array. For example: Setting groundstation's target color to yellow color
can be done in following two ways: GroundStation.TargetColor =
Yellow or GroundStation.TargetColor = [255 255 0]. This
field can be modified in the Mission Sequence as well.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
Temperature
Air temperature at ground station used to calculate tropospheric correction. GMAT only uses this value if DataSource is set to Constant.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
TroposphereModel
Integer Array or String
Any color available from the Orbit Color Picker in
GUI. Valid predefined color name or RGB triplet
value between 0 and 255.
set
DarkGray
N/A
GUI, script
Real
Real >0.0
set, get
295.1
Kelvin
script
Specification of tropospheric model used in the light time calculations.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
Enumeration
'None', 'HopfieldSaastamoinen'
set
'None'
N/A
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.
386
GroundStation
Reference Guide
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.
2.
3.
4.
5.
In the StateType menu, select Spherical.
In the HorizonReference menu, select Ellipsoid.
In the Latitude text box, type 45.
In the Longitude text box, type 270.
In the Altitude text box, type 0.1.
387
Reference Guide
GroundStation
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.
Setting Colors On a Ground Station Facility
GMAT allows you to set colors on a ground station facility that you create. The GroundStations
are drawn on the GroundTrackPlot 2D graphics display. The GroundStation object's OrbitColor
and TargetColor fields are used to set colors on a ground station facility. See the Fields section to
read more about these two fields. Also See Color documentation for discussion and examples on
how to set colors on a ground station facility.
Examples
Configure a GroundStation in Geodetic coordinates.
Create GroundStation aGroundStation
aGroundStation.CentralBody
= Earth
aGroundStation.StateType
= Spherical
aGroundStation.HorizonReference = Ellipsoid
388
GroundStation
aGroundStation.Location1
aGroundStation.Location2
aGroundStation.Location3
Reference Guide
= 60
= 45
= 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
aGroundStation.Longitude
aGroundStation.Altitude
= 59.83308194090783
= 45
= -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
Configure a GroundStation that, when used for navigation, will model how the RF signal is refracted
in the atmosphere.
Create GroundStation aGroundStation
aGroundStation.IonosphereModel
aGroundStation.TroposphereModel
= 'IRI2007';
= 'HopfieldSaastamoinen';
BeginMissionSequence;
Attach a Transmitter and Receiver resource to a GroundStation.
Create Transmitter Transmitter1
Create Receiver Receiver1
Create GroundStation aGroundStation;
389
Reference Guide
aGroundStation.AddHardware = {Transmitter1, Receiver1};
BeginMissionSequence;
390
GroundStation
Reference Guide
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, Color
Fields
Field
Description
Add
Allows the user to pick selected resources such as Spacecrafts or
GroundStations. The GroundTrackPlot object is used to draw
spacecraft's longtitude and latitude time-history on a two-dimensional
texture map of a central body that you select. After creating GroundStation object, you can also add ground stations onto the the texture
map of the central body. 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
Allowed Values
Access
Default Value
Units
Interfaces
CentralBody
Reference Array
Spacecraft, GroundStation
Set
DefaultSC
N/A
GUI, script
The central body of the Ground track plot. This field cannot be modified in the Mission Sequence.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
Resource reference
CelestialBody
set
Earth
N/A
GUI, script
391
Reference Guide
GroundTrackPlot
Field
Description
DataCollectFrequency
The number of integration steps to skip between plot points. This field
cannot be modified in the Mission Sequence.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
Maximized
Allows the user to maximize the GroundTrackPlot window. This field
cannot be modified in the Mission Sequence.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
NumPointsToRedraw
Integer
integer >= 0
set
0
N/A
GUI, script
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
Allowed Values
Access
Default Value
Units
Interfaces
392
Boolean
true,false
set
false
N/A
script
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
Allowed Values
Access
Default Value
Units
Interfaces
RelativeZOrder
Integer
integer >= 1
set
1
N/A
GUI, script
Integer
Integer ≥ 0
set
0
N/A
script
GroundTrackPlot
Reference Guide
Field
Description
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
Allowed Values
Access
Default Value
Units
Interfaces
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
Allowed Values
Access
Default Value
Units
Interfaces
SolverIterations
Boolean
True, False
set
True
N/A
GUI, script
Real array
Any Real number
set
[00]
N/A
script
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
Allowed Values
Access
Default Value
Units
Interfaces, Interfaces
Enumeration
All, Current, None
set
Current
N/A
GUI, script
393
Reference Guide
GroundTrackPlot
Field
Description
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
Allowed Values
Access
Default Value
Units
Interfaces
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
Allowed Values
Access
Default Value
Units
Interfaces
Upperleft
String
Valid File Path and Name
set
../
data/graphics/texture/ModifiedBlueMarble.jpg
N/A
GUI, script
Integer
integer > 1
set
50
N/A
GUI, script
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
Allowed Values
Access
Default Value
Units
Interfaces
Real array
Any Real number
set
[00]
None
script
GUI
Default Name and Settings for the GroundTrackPlot Resource:
394
GroundTrackPlot
Reference Guide
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
395
Reference Guide
GroundTrackPlot
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
options
Description
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:
396
GroundTrackPlot
Reference Guide
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
397
Reference Guide
BeginMissionSequence
Propagate aProp(aSat) {aSat.ElapsedDays = 2}
398
GroundTrackPlot
Reference Guide
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,ChemicalTank,BeginFiniteBurn
Fields
Field
Description
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
Allowed Values
Access
Default Value
Units
Interfaces
B
Deprecated. Z-component of the applied impulsive burn (Delta-V)
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
CoordinateSystem
String
VNB, LVLH, MJ2000Eq, SpacecraftBody
set
VNB
N/A
GUI, script
Real
Real
set, get
0
km/s
GUI, script
Determines what coordinate system the orientation parameters, Element1, Element2, and Element3 refer to. This field cannot be modified
in the Mission Sequence.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
Reference Array
Local, EarthMJ2000Eq, EarthMJ2000Ec,
EarthFixed, or any user defined system
set
Local
N/A
GUI, script
399
Reference Guide
ImpulsiveBurn
Field
Description
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
Allowed Values
Access
Default Value
Units
Interfaces
Element1
X-component of the applied impulsive burn (Delta-V)
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
Element2
Real
Real
set, get
0
km/s
GUI, script
Value of the gravitational acceleration used to calculate fuel depletion.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
400
Real
Real
set, get
0
km/s
GUI, script
Z-component of the applied impulsive burn (Delta-V)
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
GravitationalAccel
Real
Real
set, get
0
km/s
GUI, script
Y-component of the applied impulsive burn (Delta-V)
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
Element3
String
true, false
set
false
N/A
GUI, script
Real
Real > 0
set, get
9.81
m/s^2
GUI, script
ImpulsiveBurn
Reference Guide
Field
Description
Isp
Value of the specific impulse of the fuel
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
N
Deprecated. Y-component of the applied impulsive burn (Delta-V)
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
Origin
Access
Default Value
Units
Interfaces
Reference Array
Sun, Mercury, Venus, Earth, Luna,
Mars,Jupiter, Saturn, Uranus, Neptune, Pluto
set
Earth
N/A
GUI, script
ChemicalTank from which the ChemicalThruster draws propellant
from. This field cannot be modified in the Mission Sequence.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
V
Real
Real
set, get
0
km/s
GUI, script
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
Allowed Values
Tank
Real
Real
set, get
300
s
GUI, script
Reference Array
User defined list of ChemicalTanks
set
N/A
N/A
GUI, script
Deprecated. X-component of the applied impulsive burn (Delta-V)
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
Real
Real
set, get
0
km/s
GUI, script
401
Reference Guide
ImpulsiveBurn
Field
Description
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
Allowed Values
Access
Default Value
Units
Interfaces
Enumeration
Cartesian, Spherical
set
Cartesian
N/A
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.
402
ImpulsiveBurn
Reference Guide
If Decrement Mass is checked, then you can select the desired ChemicalTank 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 Yaxis is along the instantaneous orbit normal (with respect to the Earth) of the spacecraft, and the Zaxis 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.Element1 =
DefaultIB.Element2 =
DefaultIB.Element3 =
DefaultIB
-3
7
-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.
403
Reference Guide
ImpulsiveBurn
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.
Backwards-propagated Impulsive maneuvers defined using the spacecraft velocity
Examples of axes defined using the spacecraft velocity are the VNB and LVLH axes discussed
above as well as some user-defined axes. The behavior when applying an impulsive maneuver using
these types of axes during a backwards-propagation is subtle and requires some explanation. In the
examples that follow, we will focus our discussion on a VNB maneuver.
As will be shown in the script samples below, an impulsive maneuver is applied during a backwards
propagation using the ‘BackProp’ keyword. The maneuver components that you specify for a backwards propagation are used to calculate the components of the maneuver actually applied. Refer
to the script sample below where a backwards-propagated impulsive maneuver is followed by the
same maneuver using a normal formal propagation. The impulsive maneuver is defined so that the
velocity of the spacecraft is unchanged after the script is run.
Create Spacecraft Sat;
Create ImpulsiveBurn myImpulsiveBurn;
GMAT myImpulsiveBurn.CoordinateSystem = Local;
GMAT myImpulsiveBurn.Origin = Earth;
GMAT myImpulsiveBurn.Axes = VNB;
myImpulsiveBurn.Element1 = 3.1
myImpulsiveBurn.Element2 = -0.1
myImpulsiveBurn.Element3 = 0.2
BeginMissionSequence
Maneuver BackProp myImpulsiveBurn(Sat);
Maneuver myImpulsiveBurn(Sat);
To calculate the actual maneuver components applied, GMAT, internally, uses an iterative calculation
method. This iteration method works best for maneuver magnitudes that are not an appreciable fraction of the overall spacecraft velocity. In addition, for VNB maneuvers, the iteration method works
best for maneuvers where the ‘N’ and ‘B’ component magnitudes are relatively small as compared
to the 'V' component magnitude. If the GMAT internal iterative method fails to converge, a warning
message will be generated. Currently, there is not an easy way for the user to report out the actual
applied back-propagated maneuver components. (The maneuver report outputs the user supplied
VNB coordinates). After the back-propagated maneuver has been applied, however, we do know
what the components of the maneuver are. If the VNB maneuver has user-supplied components,
(Vx, Vy, Vz), then after the back-propagated maneuver has been applied, the VNB components of
the maneuver are (-Vx, -Vy, -Vz).
404
ImpulsiveBurn
Reference Guide
Consider the script sample below where the ‘N’ and ‘B’ components of the maneuver are zero and
the ‘V’ component is +5 km/s. If the spacecraft velocity is (7,0,0) km/s in J2000 inertial coordinates,
then after the backwards-propagated impulsive maneuver, the velocity of the spacecraft will be (2,0,0)
km/s.
Create Spacecraft Sat;
Create ImpulsiveBurn myImpulsiveBurn;
GMAT myImpulsiveBurn.CoordinateSystem = Local;
GMAT myImpulsiveBurn.Origin = Earth;
GMAT myImpulsiveBurn.Axes = VNB;
myImpulsiveBurn.Element1 = 5
myImpulsiveBurn.Element2 = 0.0
myImpulsiveBurn.Element3 = 0.0
BeginMissionSequence
Maneuver BackProp myImpulsiveBurn(Sat);
Finally, we note that when mass change is modeled for a backwards-propagated impulsive maneuver,
mass is added to the tank. This is done so there is no change in mass when a backwards-propagated
impulsive maneuver is followed by the same maneuver using a normal forward propagation.
Interactions
Resource
Description
Spacecraft Must be created in order to apply any ImpulsiveBurn
resource
Chemical- If you want to model mass depletion for an ImpulsiveBurn, attach a ChemicalTank
Tank
re- to the maneuvered Spacecraft as a source of fuel mass.
source
Maneuver
command
Must use the Maneuver command to apply an ImpulsiveBurn to a Spacecraft.
Vary com- If you want to allow the ImpulsiveBurn components to vary in order to achieve
mand
some goal, then the Vary command, as part of a Target or Optimize command
sequence, must be used.
Examples
Create a default ChemicalTank and an ImpulsiveBurn that allows for fuel depletion, assign the
ImpulsiveBurn the default ChemicalTank, attach the ChemicalTank to a Spacecraft, and apply
the ImpulsiveBurn to the Spacecraft.
% Create the ChemicalTank Resource
Create ChemicalTank FuelTank1
FuelTank1.AllowNegativeFuelMass = false
FuelTank1.FuelMass = 756
FuelTank1.Pressure = 1500
FuelTank1.Temperature = 20
405
Reference Guide
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 ChemicalTank to a Spacecraft
Create Spacecraft DefaultSC
DefaultSC.Tanks = {FuelTank1}
BeginMissionSequence
Maneuver DefaultIB(DefaultSC)
406
ImpulsiveBurn
Reference Guide
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, Color
Fields
Field
Description
OrbitColor Allows you to set available colors on user-defined LibrationPoint orbits. The libration point orbits are drawn using the 3D OrbitView graphics displays. Colors on a
LibrationPoint object can be set through a string or an integer array. For example:
Setting a libration point's orbit color to red can be done in the following two ways:
LibrationPoint.OrbitColor = Red or LibrationPoint.OrbitColor
= [255 0 0]. This field can be modified in the Mission Sequence as well..
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
Point
Integer Array or String
Any color available from the Orbit Color Picker in GUI.
Valid predefined color name or RGB triplet value between
0 and 255.
set
GreenYellow
N/A
GUI, script
The libration point index.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
String
L1, L2, L3, L4, or L5
set
L1
N/A
GUI, script
407
Reference Guide
LibrationPoint
Field
Description
Primary
The primary body or barycenter.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
String
CelestialBody or Barycenter. Primary cannot be SolarSystemBarycenter and Primary cannot be the same as
Secondary.
set
Sun
N/A
GUI, script
Secondary The secondary body or barycenter.
Secondary
Allowed Values
Access
Default Value
Units
Interfaces
String
CelestialBody or Barycenter. Secondary cannot be SolarSystemBarycenter and Primary cannot be the same as
Secondary.
set
Earth
N/A
GUI, script
TargetCol- Allows you to set available colors on LibrationPoint object's perturbing orbital traor
jectories that are drawn during iterative processes such as Differential Correction or
Optimization. The target color can be identified through a string or an integer array.
For example: Setting a libration point's perturbing trajectory color to yellow can be
done in following two ways: LibrationPoint.TargetColor = Yellow or
LibrationPoint.TargetColor = [255 255 0]. This field can be modified
in the Mission Sequence as well.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
408
Integer Array or String
Any color available from the Orbit Color Picker in GUI.
Valid predefined color name or RGB triplet value between
0 and 255.
set
DarkGray
N/A
GUI, script
LibrationPoint
Reference Guide
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.
409
Reference Guide
LibrationPoint
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.
Setting Colors On Libration Point Orbits
GMAT allows you to assign colors to libration point orbits that are drawn using the OrbitView
graphics display windows. GMAT also allows you to assign colors to perturbing libration point orbital
trajectories which are drawn during iterative processes such as differential correction or optimization.
The LibrationPoint object's OrbitColor and TargetColor fields are used to assign colors to both
orbital and perturbing trajectories. See the Fields section to learn more about these two fields. Also
see Color documentation for discussion and examples on how to set colors on a libration point orbit.
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
410
LibrationPoint
Reference Guide
% 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
411
Reference Guide
LibrationPoint
% 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})
412
Reference Guide
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 builtin function, with some limitations. See the CallMatlabFunction reference for details. Both usercreated 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
Field
Description
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
Allowed Values
Access
Default Value
Units
Interfaces
String
Valid file path(s)
set, get
MATLAB_FUNCTION_PATH properties in the startup file
N/A
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.
413
Reference Guide
MatlabFunction
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
414
MatlabFunction
Reference Guide
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
415
416
Reference Guide
NuclearPowerSystem
A nuclear power system
Description
The NuclearPowerSystem models a nuclear power system including power generated as function
of time and distance from the sun.
For a complete descripton of how to configure all Resources required for electric propulsion modelling, see the Tutorial named Electric Propulsion
See Also ElectricTank, ElectricThruster, SolarPowerSystem
Fields
Field
Description
AnnualDecayRate
The annual decay rate of the power system.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
BusCoeff1
Coefficient of power required by spacecraft bus.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
BusCoeff2
Real
Real
set
0.3
kW
GUI, script
Coefficient of power required by spacecraft bus.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
BusCoeff3
Real
0 <=Real <= 100
set
5
Percent/Year
GUI, script
Real
Real
set
0
kW*AU
GUI, script
Coefficient of power required by spacecraft bus.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
Real
Real
set
0
kw*AU2
GUI, script
417
Reference Guide
NuclearPowerSystem
Field
Description
EpochFormat
The epoch format for the PowerInitialEpoch field.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
InitialEpoch
The initial epoch of the system used to define power system
elapsed lifetime.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
InitialMaxPower
Real
Real >= 0
set
1.2
kW
GUI, script
The required margin between power left after power bus, and power used by the propulsion system.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
GUI
The GUI for the NuclearPowerSystem is shown below.
418
String
Valid GMAT Epoch consistent with
PowerInitialEpochFormat
set
01 Jan 2000 11:59:27.966
N/A
GUI, script
The maximum power generated at the PowerInitialEpoch.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
Margin
String
Valid Epoch format.
set
UTCGregorian
N/A
GUI, script
Real
0 <=Real <= 100
set
5
Percent
GUI, script
NuclearPowerSystem
Reference Guide
Remarks
Computation of Base Power
The NuclearPowerSystem models power degradation as a function of time. You must provide
a power system initial epoch, the power generated at that epoch, and an annual power decay rate.
Additionally, the AnnualDecayRate field models the power degredation on a per year basis. The
base power is computed using
where "tau" is the power AnnualDecayRate, P_0 is InitialMaxPower, and "delta t" is the elapsed
time between the simulation epoch and InitialEpoch.
Computation of Bus Power
The power required by the spacecraft bus for all subsystems other than the propulsion system is
computed using
where A_Bus, B_Bus, and C_Bus are BusCoeff1, BusCoeff2, and BusCoeff3 respectively and r is
the distance from the Sun in Au.
Computation of Power Available for Propulsion
Total power is compute using
Thrust power available for electric propulsion is finaly computed using
419
Reference Guide
NuclearPowerSystem
Where "delta M" is power Margin.
Examples
Create a NuclearPowerSystem and attach it to a Spacecraft.
Create Spacecraft DefaultSC
DefaultSC.PowerSystem = NuclearPowerSystem1
Create NuclearPowerSystem NuclearPowerSystem1
BeginMissionSequence
For a complete descripton of how to configure all Resources required for electric propulsion modeling, see the Tutorial named Electric Propulsion.
420
Reference Guide
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, Color
Fields
Field
Description
Add
This field allows you to add a Spacecraft, Celestial body, Libration
Point, or Barycenter resource to a plot. When creating a plot, the
Earth is added as a default body and may be removed at any time. You
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
Allowed Values
Access
Default Value
Units
Interfaces
Reference Array
Spacecraft, CelestialBody,
Point, Barycenter
set
DefaultSC, Earth
N/A
GUI, script
Libration-
421
Reference Guide
OrbitView
Field
Description
Axes
Allows you 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
Allowed Values
Access
Default Value
Units
Interfaces
EclipticPlane
Allows you to draw a grid representing the Ecliptic Plane in an OrbitView plot. This field cannot be modified in the Mission Sequence.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
CoordinateSystem
Boolean
On, Off
set
Off
N/A
GUI, script
Allows you 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 you 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
Allowed Values
Access
Default Value
Units
Interfaces
422
Boolean
On, Off
set
On
N/A
GUI, script
String
CoordinateSystem resource
set
EarthMJ2000Eq
N/A
GUI, script
OrbitView
Reference Guide
Field
Description
DataCollectFrequency
Allows you 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
Allowed Values
Access
Default Value
Units
Interfaces
DrawObject
The DrawObject field allows you the option of displaying Spacecraft
or Celestial resources on the OrbitView plot. This field cannot be
modified in the Mission Sequence.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
EnableConstellations
Boolean array
true, false
set
[true true]
N/A
GUI, script
Allows you the option of displaying star constellations on the OrbitView Plot. This field cannot be modified in the Mission Sequence.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
EnableStars
Integer
Integer ≥ 1
set
1
N/A
GUI, script
Boolean
On, Off
set
On
N/A
GUI, script
This field gives you 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
Allowed Values
Access
Default Value
Units
Interfaces
Boolean
On, Off
set
On
N/A
GUI, script
423
Reference Guide
OrbitView
Field
Description
Grid
Allows you 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
Allowed Values
Access
Default Value
Units
Interfaces
Maximized
Allows you to maximize the OrbitView plot window. This field cannot
be modified in the Mission Sequence.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
NumPointsToRedraw
Integer
Integer ≥ 1
set
0
N/A
GUI, script
Allows you 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
Allowed Values
Access
Default Value
Units
Interfaces
424
Boolean
True, False
set
false
N/A
script
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
Allowed Values
Access
Default Value
Units
Interfaces
RelativeZOrder
Boolean
On, Off
set
Off
N/A
GUI, script
Integer
Integer ≥ 0
set
0
N/A
script
OrbitView
Reference Guide
Field
Description
ShowPlot
Allows you 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
Allowed Values
Access
Default Value
Units
Interfaces
ShowLabels
Allows you to turn on or off spacecraft and celestial body Object labels. If you select true, then spacecraft and celestial body object labels
will show up in orbit view plot. If you select false, then spacecraft and
celestial body labels will not be shown in the orbit plot. This field cannot be modified in the Mission Sequence.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
Size
Boolean
True, False
set
True
N/A
GUI, script
Boolean
True, False
set
True
N/A
GUI, script
Allows you 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
Allowed Values
Access
Default Value
Units
Interfaces
Real array
Any Real number
set
[0 0]
N/A
script
425
Reference Guide
OrbitView
Field
Description
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
Allowed Values
Access
Default Value
Units
Interfaces
StarCount
Allows you 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
Allowed Values
Access
Default Value
Units
Interfaces
SunLine
Integer
Integer ≥ 1
set
7000
N/A
GUI, script
Allows you 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
Allowed Values
Access
Default Value
Units
Interfaces
426
Enumeration
All, Current, None
set
Current
N/A
GUI, script
Boolean
On, Off
set
Off
N/A
GUI, script
OrbitView
Reference Guide
Field
Description
UpdatePlotFrequency
This field lets you 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
Allowed Values
Access
Default Value
Units
Interfaces
UpperLeft
Allows you 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
Allowed Values
Access
Default Value
Units
Interfaces
UseInitialView
Integer
Integer ≥ 1
set
50
N/A
GUI, script
Real array
Any Real number
set
[0 0]
N/A
script
This field lets you 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 you change 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
Allowed Values
Access
Default Value
Units
Interfaces
Boolean
On, Off
set
On
N/A
GUI, script
427
Reference Guide
OrbitView
Field
Description
ViewDirection
Allows you to select the direction of view in an OrbitView plot. You
can specify the view direction by choosing a resource to point at such
as a Spacecraft, Celestial body, Libration Point, or Barycenter.
Alternatively, you can also 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
Allowed Values
Access
Default Value
Units
Interfaces
ViewPointReference
This optional field allows you 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
Allowed Values
Access
Default Value
Units
Interfaces
428
Reference array
Spacecraft, CelestialBody, LibrationPoint, Barycenter, or a 3-vector of numerical values
set
Earth
km or N/A
GUI, script
Reference array
Spacecraft, CelestialBody, LibrationPoint, Barycenter, or a 3-vector of numerical values
set
Earth
km or N/A
GUI, script
OrbitView
Reference Guide
Field
Description
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 you. This field cannot be modified in the Mission
Sequence.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
ViewScaleFactor
This field scales ViewPointVector before adding it to ViewPointReference. The ViewScaleFactor allows you to back away from an object to fit in the field of view. This field cannot be modified in the
Mission Sequence.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
ViewUpAxis
Reference array
Spacecraft, CelestialBody, LibrationPoint, Barycenter, or a 3-vector of numerical values
set
[30000 0 0]
km or N/A
GUI, script
Real
Real Number ≥ 0
set
1
N/A
GUI, script
This field lets you 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
Allowed Values
Access
Default Value
Units
Interfaces
Enumeration
X , -X , Y , -Y , Z , -Z
set
Z
N/A
GUI, script
429
Reference Guide
OrbitView
Field
Description
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 allows
you 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 you 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
Allowed Values
Access
Default Value
Units
Interfaces
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
Allowed Values
Access
Default Value
Units
Interfaces
XYPlane
String
CoordinateSystem resource
set
EarthMJ2000Eq
N/A
GUI, script
Boolean
Off, On
set
Off
N/A
GUI, script
Allows you 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
Allowed Values
Access
Default Value
Units
Interfaces
Boolean
On, Off
set
On
N/A
GUI, script
GUI
The figure below shows the default settings for the OrbitView resource:
430
OrbitView
Reference Guide
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.
Control
Description
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
431
Reference Guide
OrbitView
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
options
Description
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 you may create.
432
OrbitView
Reference Guide
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}
OrbitView View Definition Controls
GMAT is capable of drawing orbit plots that allow you to visualize the motion of spacecraft and
celestial bodies throughout the mission sequence. Here we discuss the options you can use in setting
up and viewing Orbit plots. You can choose many properties including the coordinate system of the
orbit view plot and the view location and direction from where visualizations can be seen. The script
snippet below shows how to create OrbitView resource that includes key view definition controls
fields as well. Detailed definitions of all fields for OrbitView resource can be found in Fields section.
Create OrbitView PlotName
PlotName.CoordinateSystenm
PlotName.Add
= CoordinateSystemName
= [SpacecraftName, BodyName, ...
LibrationPoint, Barycenter]
PlotName.ViewPointReference
= [ObjectName, VectorName]
PlotName.ViewPointVector
= [ObjectName, VectorName]
PlotName.ViewDirection
= [ObjectName, VectorName]
PlotName.ViewScaleFactor
= [Real Number]
PlotName.ViewUpCoordinateSystem = CoordinateSystemName
PlotName.ViewUpAxis
= [X,-X,Y,-Y,Z,-Z];
You can specify the view location and direction of OrbitView plot object by using the ViewPointReference, ViewPointVector, ViewDirection, ViewUpCoordinateSystem and ViewUpAxis fields. Figure below shows a graphical definition of ViewPointReference, ViewPointVector,
and ViewDirection fields and how they determine the actual view location and view direction. You
can supply ViewPointReference, ViewPointVector and ViewDirection fields by either giving a
vector in the format [x y z] or by specifying an object name. If a vector is given for one of the quantities, then we simply use it in its appropriate place in the computations below. If an object is given,
we must determine the vector associated with it. The rest of this section is devoted in determining
ViewPointReference, ViewPointVector and ViewDirection fields if you specify an object.
433
Reference Guide
OrbitView
ViewPointReference field defines the point from which ViewPointVector is measured. If an object
is given for ViewPointReference field, i.e. when you have the following in the sample script:
MyOrbitViewPlot.CoordinateSystenm
MyOrbitViewPlot.ViewPointReference
= MyCoordSys
= ViewRefObject
then we need to determine rr as illustrated in above figure. If ViewRefObject is the same as the origin
of MyCoordSys, then rr = [0 0 0]. Otherwise rr is the cartesian position of ViewPointReference
in MyCoordSys.
ViewPointVector field points from ViewPointReference (rr) in the direction of the view point
location. If an object is given for ViewPointVector field, i.e. you have the following in the sample
script:
MyOrbitViewPlot.CoordinateSystenm
MyOrbitViewPlot.ViewPointVector
= MyCoordSys
= ViewPointObject
then we need to determine rv as illustrated in above figure by using the coordinate system conversion
routine to calculate the following:
434
OrbitView
Reference Guide
We now know everything to calculate the location of the view point in the desired coordinate system.
From inspection of the above figure, we see that the relation is:
Now that we know the view point location, we need to determine the ViewDirection: rd as illustrated
in above figure. If a vector was specified for ViewDirection field, then no computations are required.
However, if an object was given as shown in the following sample script:
MyOrbitViewPlot.CoordinateSystenm
MyOrbitViewPlot.ViewDiection
= MyCoordSys
= ViewDirectionObject
then we calculate rd from the following:
Note that ViewDirection vector rd must not be zero vector [0 0 0].
ViewUpCoordinateSystem and ViewUpAxis fields are used to determine which direction appears
as up in an OrbitView plot. Most of the time, coordinate system chosen under ViewUpCoordinateSystem field will be the same as the coordinate system selected under the CoordinateSystem
field. ViewUpAxis field allows you to define which axis of the ViewUpCoordinateSystem field
will appear as the up direction in an orbit plot.
Below are some examples that show how to generate OrbitView plots using different View Definition Controls configurations:
Earth Inertial view with spacecraft: This example shows orbit view plot with Earth and a spacecraft.
Since ViewPointReference field is set to an object (i.e. Earth), hence ViewPointRef vector in above
figure is [0 0 0] in EarthMJ2000Eq coordinate system. The ViewPointVector field is set to a vector
( i.e. set to [0 0 40000] ). This means that the view is from 40000 km above the Earth's equatorial plane on the z-axis of the EarthMJ2000Eq coordinate system. The view direction (specified in
ViewDirection field) is towards the earth.
Create Spacecraft aSat
Create Propagator aProp
Create OrbitView anOrbitView
anOrbitView.Add = {aSat, Earth}
anOrbitView.CoordinateSystem = EarthMJ2000Eq
anOrbitView.ViewPointReference = Earth
anOrbitView.ViewPointVector = [ 0 0 40000 ]
anOrbitView.ViewDirection = Earth
435
Reference Guide
OrbitView
anOrbitView.ViewScaleFactor = 1
anOrbitView.ViewUpCoordinateSystem = EarthMJ2000Eq
anOrbitView.ViewUpAxis = Z
BeginMissionSequence
Propagate aProp(aSat) {aSat.ElapsedDays = 1}
Earth Inertial view with spacecraft and Luna: This example shows orbit view plot with Earth, spacecraft and Moon. Note ViewPointReference field is set to an object (i.e. Earth), hence ViewPointRef
vector in above figure = [0 0 0] in EarthMJ2000Eq coordinate system. ViewPointVector field is still
set to a vector ( i.e. set to [0 0 500000] ). This means that the view is from 500000 km above the
Earth's equatorial plane on the z-axis of the EarthMJ2000Eq coordinate system. ViewDirection
field defines the view direction which is set towards the earth.
Create Spacecraft aSat
Create Propagator aProp
Create OrbitView anOrbitView
anOrbitView.Add = {aSat, Earth, Luna}
anOrbitView.CoordinateSystem = EarthMJ2000Eq
anOrbitView.ViewPointReference = Earth
anOrbitView.ViewPointVector = [ 0 0 500000 ]
anOrbitView.ViewDirection = Earth
anOrbitView.ViewScaleFactor = 1
anOrbitView.ViewUpCoordinateSystem = EarthMJ2000Eq
anOrbitView.ViewUpAxis = Z
BeginMissionSequence
Propagate aProp(aSat) {aSat.ElapsedDays = 5}
View of spacecraft from Luna in Earth inertial frame: This example of an orbit view plot shows
spacecraft as viewed from Luna orbiting around Earth in an inertial reference frame. ViewPointReference field is set to an object (i.e. Earth), hence ViewPointRef vector is [0 0 0] in EarthMJ2000Eq
coordinate system. This time ViewPointVector field is set to an object (i.e. Luna ). This means that
the spacecraft will be seen from the vantage point of Luna. Note that ViewDirection field is set to
spacecraft (aSat). This means that view direction as seen from Luna is towards the spacecraft. After
you run this example, re-run this example but this time with ViewScaleFactor field set to 2 and see
what happens. You'll notice that ViewScaleFactor simply scales ViewPointVector field.
Create Spacecraft aSat
Create Propagator aProp
Create OrbitView anOrbitView
anOrbitView.Add = {aSat, Earth, Luna}
436
OrbitView
Reference Guide
anOrbitView.CoordinateSystem = EarthMJ2000Eq
anOrbitView.ViewPointReference = Earth
anOrbitView.ViewPointVector = Luna
anOrbitView.ViewDirection = aSat
anOrbitView.ViewScaleFactor = 1
anOrbitView.ViewUpCoordinateSystem = EarthMJ2000Eq
anOrbitView.ViewUpAxis = Z
BeginMissionSequence
Propagate aProp(aSat) {aSat.ElapsedDays = 5}
View towards Luna from Earth as spacecraft orbits around Luna in inertial frame: This example of
an orbit view plot shows view of Luna from vantage point of Earth as a spacecraft orbits around
Luna. ViewPointReference field is set to an object (i.e. Luna), hence ViewPointRef vector in above
figure is [0 0 0] in LunaMJ2000Eq coordinate system. ViewPointVector field is set to an object (i.e.
Earth ). This means that the camera or vantage point is located at Earth. ViewDirection field is also
set to an object (i.e. Luna). This means that view direction as seen from Earth is towards 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, Earth}
anOrbitView.CoordinateSystem = LunaMJ2000Eq
anOrbitView.ViewPointReference = Luna
anOrbitView.ViewPointVector = Earth
anOrbitView.ViewDirection = Luna
anOrbitView.ViewScaleFactor = 1;
anOrbitView.ViewUpCoordinateSystem = LunaMJ2000Eq;
anOrbitView.ViewUpAxis = Z;
437
Reference Guide
OrbitView
BeginMissionSequence
Propagate aProp(aSat) {aSat.ElapsedDays = 5}
View towards spacecraft1 from spacecraft2 in inertial frame: This example of an orbit view plot
shows spacecraft1 (aSat1) being viewed from spacecraft2 (aSat2) as they move in inertial reference
frame. ViewPointReference field is set to an object (i.e. Earth), hence ViewPointRef vector in above
figure is [0 0 0] in EarthMJ2000Eq coordinate system. ViewPointVector field is set to an object (i.e.
aSat2 ) and ViewDirection field is also set to an object (i.e. aSat1). This means that aSat1 will be
viewed from the vantage point of aSat2.
Create Spacecraft aSat aSat2
aSat2.X = 19500
aSat2.Z = 10000
Create Propagator aProp
Create OrbitView anOrbitView
anOrbitView.Add = {aSat, aSat2, Earth,}
anOrbitView.CoordinateSystem = EarthMJ2000Eq
anOrbitView.ViewPointReference = Earth
anOrbitView.ViewPointVector = aSat2
anOrbitView.ViewDirection = aSat
anOrbitView.ViewScaleFactor = 1.0
anOrbitView.ViewUpCoordinateSystem = EarthMJ2000Eq
anOrbitView.ViewUpAxis = Z
BeginMissionSequence
Propagate aProp(aSat, aSat2){aSat.ElapsedSecs = 12000.0}
Orbit view plot of Sun-Earth-Moon L1 Rotating System: This example of an orbit view plot shows
the Earth and spacecraft in the Sun-Earth-Moon rotating coordinate system. ViewPointReference
field is set to an object (i.e. ESL1), hence ViewPointRef vector in above figure is [0 0 0] in SunEarthMoonL1 rotating coordinate system. ViewPointVector field is set to a vector (i.e. [0 0 30000] ). This
means that the view is taken from 30000 km above the SunEarthMoonL1 coordinate system's XY
plane on the z-axis of the SunEarthMoonL1 coordinate system. ViewDirection field is also set to
an object (i.e. ESL1). This means that view direction as seen from 30000 km above the SunEarthMoonL1 coordinate system's XY plane is towards ESL1. Note that in this example, ViewScaleFactor is set to 25. This simply scales or amplifies ViewPointVector field 25 times its original value.
Create Spacecraft aSat
GMAT
GMAT
GMAT
GMAT
GMAT
438
aSat.DateFormat = UTCGregorian;
aSat.Epoch = '01 Apr 2013 00:00:00.000'
aSat.CoordinateSystem = EarthMJ2000Eq
aSat.DisplayStateType = Cartesian
aSat.X = 1429457.8833484
OrbitView
Reference Guide
GMAT
GMAT
GMAT
GMAT
GMAT
aSat.Y = 147717.32846679
aSat.Z = -86529.655549364
aSat.VX = -0.037489820883615
aSat.VY = 0.32032521614858
aSat.VZ = 0.15762889268226
Create Barycenter EarthMoonBarycenter
GMAT EarthMoonBarycenter.BodyNames = {Earth, Luna}
Create LibrationPoint ESL1
GMAT ESL1.Primary = Sun
GMAT ESL1.Secondary = EarthMoonBarycenter
GMAT ESL1.Point = L1
Create ForceModel aFM
aFM.CentralBody = Earth
aFM.PointMasses = {Luna, Sun}
Create Propagator aProp
aProp.FM = aFM
Create CoordinateSystem SunEarthMoonL1
GMAT SunEarthMoonL1.Origin = ESL1
GMAT SunEarthMoonL1.Axes = ObjectReferenced
GMAT SunEarthMoonL1.XAxis = R
GMAT SunEarthMoonL1.ZAxis = N
GMAT SunEarthMoonL1.Primary = Sun
GMAT SunEarthMoonL1.Secondary = EarthMoonBarycenter
Create OrbitView anOrbitView
anOrbitView.Add = {aSat, Earth, Sun}
anOrbitView.CoordinateSystem = SunEarthMoonL1
anOrbitView.ViewPointReference = ESL1
anOrbitView.ViewPointVector = [ 0 0 30000 ]
anOrbitView.ViewDirection = ESL1
anOrbitView.ViewScaleFactor = 25
anOrbitView.ViewUpCoordinateSystem = SunEarthMoonL1
anOrbitView.ViewUpAxis = Z
BeginMissionSequence
Propagate aProp(aSat) {aSat.ElapsedDays = 15}
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.
439
Reference Guide
OrbitView
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
440
OrbitView
Reference Guide
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
441
Reference Guide
OrbitView
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 outgoing 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'
442
OrbitView
Reference Guide
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}
443
444
Reference Guide
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 or Code500 ephemeris files
for propagation. 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:
•
•
•
•
For numerical Propagator documentation see Numerical Propagator
For ForceModel documentation see Force Model
For SPICE Propagator documentation see SPK-Configured Propagator
For Code500 ephemeris Propagator documentation see Code500 Ephemeris-Configured Propagator
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.
445
Reference Guide
Propagator
Options
Option
Description
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
Allowed Values
Default Value
Interfaces
Access
Units
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
Allowed Values
Default Value
Interfaces
Access
Units
InitialStepSize
Real
Real > 0.0001
60
GUI, script
set
sec.
The lower bound on integration error, used to determine when to make
the step size larger. Applies only to AdamsBashforthMoulton integrator.
Data Type
Allowed Values
Default Value
Interfaces
Access
Units
446
Resource reference
ForceModel
N/A
GUI, script
set
N/A
The size of the first step attempted by the integrator.
Data Type
Allowed Values
Default Value
Interfaces
Access
Units
LowerError
Real
Real > 0 AND Real < 1
1e-11 except for ABM integrator which is 1e-10
GUI, script
set
N/A
Real
Real > 0 AND 0 < LowerError <TargetError
< Accuracy
1e-13
GUI, script
set
N/A
Propagator
Reference Guide
Option
Description
MaxStep
The maximum allowable step size.
Data Type
Allowed Values
Default Value
Interfaces
Access
Units
MaxStepAttempts
The number of attempts the integrator takes to meet the tolerance defined
by the Accuracy field.
Data Type
Allowed Values
Default Value
Interfaces
Access
Units
MinStep
Real
Real > 0 AND MinStep <= MaxStep
2700
GUI, script
set
N/A
Integer
Integer >= 1
50
GUI, script
set
N/A
The minimum allowable step size.
Data Type
Allowed Values
Default Value
Interfaces
Access
Units
Real
Real > 0 AND MinStep <= MaxStep
0.001
GUI, script
set
sec.
StopIfAccuracy-IsVi- Flag to stop propagation if integration error value defined by Accuracy
olated
is not satisfied.
Data Type
Allowed Values
Default Value
Interfaces
Access
Units
TargetError
Boolean
true, false
true
GUI, script
set
N/A
The nominal bound on integration error, used to set the target integration accuracy when adjusting step size. Applies only to AdamsBashforthMoulton integrator.
Data Type
Allowed Values
Default Value
Interfaces
Access
Units
Real
Real > 0 AND 0 < LowerError < TargetError
< Accuracy
1e-11
GUI, script
set
N/A
447
Reference Guide
Propagator
Option
Description
Type
Specifies the integrator or analytic propagator used to model the time evolution of spacecraft motion.
Data Type
Allowed Values
Default Value
Interfaces
Access
Units
Enumeration
PrinceDormand78,
PrinceDormand853,
PrinceDormand45,
RungeKutta89,RungeKutta68,
RungeKutta56,
AdamsBashforthMoulton,
SPK,
Code500
RungeKutta89
GUI, script
set
N/A
GUI
Settings for the embedded Runge-Kutta integrators. Select the desired integrator from the Type
menu.
448
Propagator
Reference Guide
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.
449
Reference Guide
Propagator
Option
Description
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.
PrinceDormand853
An adaptive step, eighth order Runge-Kutta integrator with 5th
order error control that incorporates a 3rd order correction, as
described in section II.10 of "Solving Ordinary Differential Equations I: Nonstiff Problems" by Hairer, Norsett and Warner. The
coefficients were derived by Prince and Dormand. This integrator
performs surprisingly well at loose Accuracy settings.
PrinceDormand45
An 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 nonconservative 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
450
Propagator
Reference Guide
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.
Orbit
Dynamics Model
Duration
LEO
Earth 20x20, Sun, Moon, drag using 1 day
MSISE90 density, SRP
Molniya
Earth 20x20, Sun, Moon, drag using Jacchia 3 days
Roberts density, SRP
Mars Transfer
Near Earth: Earth 8x8, Sun, Moon, SRP
333 days
Deep Space: All planets as point mass perturbations
Near Mars: Mars 8x8 SRP
Lunar Transfer
Earth central body with all planets as point 5.8 days
mass perturbations
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 an451
Reference Guide
Propagator
other 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
452
Propagator
Reference Guide
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
Option
Description
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
Allowed Values
Access
Default Value
Units
Interfaces
Drag
Resource reference
CelestialBody
set
Earth
N/A
GUI, script
Deprecated. This field
Drag.AtmosphereModel.
has
been
replaced
with
453
Reference Guide
Propagator
Option
Description
Drag.AtmosphereModel
Specifies the atmosphere model used in the drag force. This
field is only active if there is a PrimaryBody.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
Drag.CSSISpaceWeatherFile
Access
Default Value
Units
Interfaces
String
String containing name of the CSSI
file with optional path information.
set
'CSSI_2004To2026.txt'
N/A
GUI, script
Enabled when Drag.AtmosphereModel is MarsGRAM2005. Specifies the Mars-GRAM density model to use.
Mean is mean density with any optional wave model perturbations enabled by the input file. High is Mean density plus
1 standard deviation. Low is Mean density minus 1 standard
deviation.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
454
If PrimaryBody is Mars: None,
MarsGRAM2005 (with plugin)
set
None
N/A
GUI, script
The file name of the CSSI space weather file with optional
path information. See Remarks for details on file format.
Data Type
Allowed Values
Drag.DensityModel
Enumeration
If
PrimaryBody
is
Earth:
None, JacchiaRoberts, MSISE86,
MSISE90
(with
plugin),
NRLMSISE00 (with plugin)
Enumeration
High, Low, Mean
set
Mean
N/A
script
Propagator
Reference Guide
Option
Description
Drag.F107
The instantaneous value of solar flux at wavelength of 10.7 cm.
This field is only active if there is a PrimaryBody. Realistic
values for this seeting are 50 <= Drag.F107 <= 400.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
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. Realistic values for this seeting are 50 <= Drag.F107A
<= 400.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
Drag.HistoricWeatherSource
Real
Drag.F107>= 0
set
150
10^-22 W/m^2/Hz
GUI, script
Real
Drag.F107A>=0
set
150
10^-22 W/m^2/Hz
script
Defines the source for historical flux and Geo-magnetic indeces used in Earth density modeling.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
Enumeration
ConstantFluxAndGeoMag,
CSSISpaceWeatherFile
set
ConstantFluxAndGeoMag
N/A
GUI, script
455
Reference Guide
Propagator
Option
Description
Drag.InputFile
Enabled when Drag.AtmosphereModel is MarsGRAM2005. Path to the Mars-GRAM input namelist file
that configures the model. See the MarsGRAM2005 section [464] for details on the individual settings in this file
and how they are used by GMAT. Relative paths are relative
to the GMAT bin directory.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
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
Allowed Values
Access
Default Value
Units
Interfaces
Drag.PredictedWeatherSource
Real
0 <= Real Number <= 9
set
3
N/A
script
Defines the source for predicted flux and Geo-magnetic indeces used in Earth density modeling.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
456
String
Valid path to a Mars-GRAM input
namelist file
set
'../
data/atmosphere/MarsGRAM2005/inputstd0.txt'
N/A
script
Enumeration
SchattenFile, CSSISpaceWeatherFile
set
ConstantFluxAndGeoMag
N/A
GUI, script
Propagator
Reference Guide
Option
Description
Drag.SchattenErrorModel
The error model used from the Schatten file. Schatten predicts
include mean, +2 sigma, and -2 sigma models. See Remarks
for details on the file format.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
Drag.SchattenFile
Mi-
The file name of the Schatten file with optional path information. See Remarks for details on file format.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
Drag.SchattenTimingModel
Enumeration
Nominal, PlusTwoSigma,
nusTwoSigma
set
Nominal
N/A
GUI, script
String
String containing name of the Schatten file with optional path information.
set
'SchattenPredict.txt'
N/A
GUI, script
The timing model used from the Schatten file. Schatten predicts include a nominal solar cycle model, an early model, and
a late model. See Remarks for details on the file format.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
Enumeration
NominalCycle, EarlyCycle, LateCycle
set
NominalCycle
N/A
GUI, script
457
Reference Guide
Propagator
Option
Description
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
Allowed Values
Access
Default Value
Units
Interfaces
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
Allowed Values
Access
Default Value
Units
Interfaces
GravityField.
PrimaryBodyName.Degree
Enumeration
None, SolidAndPole
set
None
N/A
script
The degree of the harmonic gravity field. This field is only
active if there is a PrimaryBody.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
458
Enumeration
None,
RSSStep,
RSSState,
LargestState, LargestStep
set
RSSStep
N/A
GUI, script
Integer
0<Degree<Max Degree On File
set
4 (When loading a custom file in the
GUI, GMAT sets Degree to the max
value on the file)
N/A
GUI, script
Propagator
Reference Guide
Option
Description
GravityField.
PrimaryBodyName.Order
The order of the harmonic gravity field. This field is only active
if there is a PrimaryBody.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
Integer
0<Order<Max Degree On File
AND Degree <= Order
set
4 (When loading a custom file in the
GUI, GMAT sets Order to the max
value on the file)
N/A
GUI, script
GravityField.
The gravity potential file. This field is only active if there is a
PrimaryBodyName.PotentialFile PrimaryBody. See discussion below for detailed explanation
of supported file types and how to configure gravity files.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
Model
String
path and name of .cof OR .grv file
set
JGM2.cof
N/A
GUI, script
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
Allowed Values
Access
Default Value
Units
Interfaces
String
JGM-2,
JGM-3,
EGM-96,
Mars-50C, MGNP-180U
set,get
JGM-2
N/A
GUI
459
Reference Guide
Propagator
Option
Description
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
Allowed Values
Access
Default Value
Units
Interfaces
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
Allowed Values
Access
Default Value
Units
Interfaces
RelativisticCorrection
included
in
Enumeration
On, Off
set
Off
N/A
GUI, script
Sets SRP force on or off. See the Remarks section for a detailed
explanation of SRP configuration. The SRP model used is set
in the SRP.Model field.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
460
Resource reference
CelestialBody not
PointMasses.
set
Earth
N/A
GUI, script
Sets relativistic correction on or off.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
SRP
Resource array
array of CelestialBodies not selected as PrimaryBody
set
Empty List
N/A
GUI, script
Enumeration
On, Off
set
Off
N/A
GUI, script
Propagator
Reference Guide
Option
Description
SRP.Flux
The value of SRP flux at 1 AU. This field is only active in the
script if SRP is on.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
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
Allowed Values
Access
Default Value
Units
Interfaces
SRP.Model
Real
4.33e-6 < SRP.Flux_Pressure <
4.84e-6
set
4.55982118135874e-006
W *s/m^3
script
The model for SRP acceleration.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
SRP.Nominal_Sun
Real
1200 <SRP.Flux < 1450
set
1367
W/m^2
script
Enumeration
Spherical,SPADFile
set
Spherical
N/A
GUI, script
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
Allowed Values
Access
Default Value
Units
Interfaces
Real
135e6<Nominal_Sun<165e6
set
149597870.691
km
script
461
Reference Guide
Propagator
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.
462
Propagator
Reference Guide
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
EGM96_FILE
= DATA_PATH/gravity/earth/
= 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
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 associated with density
configuration, such as Drag.F107, Drag.F107A, and Drag.MagneticIndex and others 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.
463
Reference Guide
Propagator
Model
Theoretical Altitude (h) Comments
Limits
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.
NRLMSISE00
0 < 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.
MarsGRAM2005
When PrimaryBody is Mars, you can choose Mars-GRAM 2005 as your atmosphere model. This
model is only available when the libMarsGRAM plugin is available and enabled in the GMAT startup
file.
Warning
As of version R2015a, you can only have one unique Mars-GRAM force model configuration in a given script. If you include multiple propagators with Mars-GRAM force
models with different Mars-GRAM configurations, the different configurations are not
honored, and all of the propagators will use the same configuration for Mars-GRAM.
When using the MarsGRAM2005 atmosphere model, three new fields are available in the script
language (but not the GUI):
• Drag.InputFile
• Drag.DensityModel
See the Fields section for details on these fields.
In addition, the space weather fields are treated as follows:
• Drag.F107: value of 10.7 cm solar flux at 1 AU, as documented in the Fields section
• Drag.F107A: not used
• Drag.MagneticIndex: not used
The Mars-GRAM 2005 input file is a text file in FORTRAN NAMELIST format. Most variables
in this file are passed directly to the Mars-GRAM model and are used as intended. However, some
are replaced internally by GMAT-supplied values. The following table lists those input variables that
are handled specially.
464
Input Variable
GMAT usage
(Unlisted)
Passed through to Mars-GRAM 2005 model
DATADIR
Always
Files'
'../data/atmosphere/MarsGRAM2005/bin-
Propagator
Reference Guide
Input Variable
GMAT usage
GCMDIR
Always
Files'
IERT
Always 1 (Earth-receive time)
IUTC
Always 0 (TT time)
MONTH
Replaced by current propagation epoch
MDAY
Replaced by current propagation epoch
MYEAR
Replaced by current propagation epoch
NPOS
Always 1
IHR
Replaced by current propagation epoch
IMIN
Replaced by current propagation epoch
ISEC
Replaced by current propagation epoch
LonEW
Always 1 (positive East)
F107
Replaced by value of Drag.F107
FLAT
Replaced by current propagation state
FLON
Replaced by current propagation state
FHGT
Replaced by current propagation state
MOLAhgts
Always 0 (reference ellipsoid)
iup
Always 0 (no output)
ipclat
Always 0 (planetographic input)
requa
Replaced by value of Mars.EquatorialRadius
rpole
Replaced by GMAT's value of Mars polar radius (calculated from
Mars.EquatorialRadius and Mars.Flattening)
'../data/atmosphere/MarsGRAM2005/bin-
The input file is read by the Mars-GRAM 2005 model code, which has limited error checking. If the
input file or data files are incorrect or missing, GMAT may exhibit unintended behavior. Note that
local winds returned by the Mars-GRAM 2005 model are not included in GMAT's drag model.
Configuring Space Weather Data for Density Models
GMAT supports several space weather input types for drag modelling including constant flux and
Geo-magnetic index values, a historical weather data file, and a predicted weather data file. You can
separately configure the data used for historical data and predicted data. For historical data you can
choose between constant values and a CSSI space weather file. For predicted data you can choose
between constant values and a Schatten predict file. Each of those sources is discussed in detail below.
The precedence for data source is determined by the simulation epoch (i.e. the epoch when density
is evaluated), and the epochs contained on the data files
• If both historical data and predicted data sources are set to constants, then constant values are
always used.
465
Reference Guide
Propagator
• If you have selected a CSSI file as the historical data source, if the simulation epoch falls before
the last row of historical data in the CSSI file's historical data block, then the CSSI data is used
(the first row is used if the simulation epoch is before the first historical data record), otherwise,
the predicted data source is used. Note: GMAT does not use any of the predicted data from the
CSSI file.
• If you have selected the Schatten file for predicted data, if the simulation epoch is NOT in the
CSSI file historical data, or the historical data source is set to constant values, then the data is
used from the Schatten file.
Constant Values
GMAT supports constant flux and Geo-magnetic index values for all Earth density models. You configure GMAT
to use those values for historical and predicted data as shown below using NRLMSISE00 for the example.
Create ForceModel aForceModel
GMAT aForceModel.Drag.AtmosphereModel = NRLMSISE00
GMAT aForceModel.Drag.HistoricWeatherSource = 'ConstantFluxAndGeoMag'
GMAT aForceModel.Drag.PredictedWeatherSource = 'ConstantFluxAndGeoMag'
GMAT aForceModel.Drag.F107 = 150
GMAT aForceModel.Drag.F107A = 150
GMAT aForceModel.Drag.MagneticIndex = 3
Historical Space Weather Data
You can provide a Center for Space Standards and Innovation (CSSI) file for historical space weather
data. GMAT does not use the predicted portion of the file but does use the historical portion of the
data. The CCSI file format is described in detail at the Celestrak website and the files are available
for download at that site and here. You configure GMAT to use historical data as shown below.
Create ForceModel aForceModel
GMAT aForceModel.Drag.AtmosphereModel = NRLMSISE00
GMAT aForceModel.Drag.HistoricWeatherSource = 'CSSISpaceWeatherFile'
GMAT aForceModel.Drag.CSSISpaceWeatherFile = 'CSSI_2004To2026.txt'
You can provide a full or relative path to the file, or put the file in GMAT’s data file folders documented in the startup file help.
Predicted Space Weather Data
You configure GMAT to use Schatten predicted data as shown below
Create ForceModel aForceModel
GMAT aForceModel.Drag.AtmosphereModel = NRLMSISE00
GMAT aForceModel.Drag.PredictedWeatherSource = 'SchattenFile'
GMAT aForceModel.Drag.SchattenFile = 'SchattenPredict.txt'
GMAT aForceModel.Drag.SchattenErrorModel = 'Nominal'
GMAT aForceModel.Drag.SchattenTimingModel = 'NominalCycle'
You can provide a full or relative path to the file, or put the file in GMAT’s data file folders documented in the startup file help. Additionally you can choose between Nominal, PlusTwoSigma,
and MinusTwoSigma for the SchattenErrorModel, and between NominalCycle, EarlyCycle,
and LateCycle for the SchattenTimingModel.
466
Propagator
Reference Guide
The Schatten file is distributed by the Flight Dynamics Facility (FDF) at Goddard Space Flight
Center. You can apply for an account to obtain Schatten file updates at the FDF Forms Interface.
Note that GMAT reads the raw file containing all permutation of mean, +2 sigma, and -2 sigma, and
nominal, early and late solar cycles. The files from the FDF must be modified to include keywords
that indicate when data starts and ends as shown below:
NOMINAL TIMING
EARLY TIMING
mo. yr. mean +2sig -2sig ap mean +2sig -2sig
BEGIN_DATA
2 2011
92 107
76
9 105 125
85
3 2011
93 110
77
9 106 128
86
4 2011
95 112
78
9 108 129
87
END_DATA
LATE TIMING
ap mean +2sig -2sig ap
10
10
10
77
79
80
87
89
92
66
67
69
8
8
8
Data must be formatted according to FORMAT(I3,I5,I6,11I5), and no comments or blank lines can
occur between the BEGIN_DATA and END_DATA keywords.
Configuring SRP Models
GMAT supports a spherical SRP model, and an SRP file for high fidelity SRP modelling. Both models
use a dual cone model for central body shadowing of the spacecraft. See the Spacecraft Ballistic/Mass
Properties documentation for configuring a SPAD file for a spacecraft. The script snippet below
shows how to configure two ForceModels, one that use Spherical and on that uses a SPADFile.
% A spherical SRP model
Create ForceModel aForceModel_1
aForceModel_1.PrimaryBodies = {Earth}
aForceModel_1.SRP = On
aForceModel_1.SRP.Model = Spherical
% A SPAD SRP model
Create ForceModel aForceModel_2
aForceModel_2.PrimaryBodies = {Earth}
aForceModel_2.SRP = On
aForceModel_2.SRP.Model = SPADFile
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
aForceModel.PrimaryBodies = {Earth}
aForceModel.SRP = On
aForceModel.SRP.Flux = 1367
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
aForceModel.PrimaryBodies = {Earth}
aForceModel.SRP = On
467
Reference Guide
Propagator
aForceModel.SRP.Flux_Pressure = 4.53443218374393e-006
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
aForceModel.PrimaryBodies = {Earth}
aForceModel.SRP = On
aForceModel.SRP.Flux = 1370
aForceModel.SRP.Nominal_Sun = 149597870
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
468
Propagator
Reference Guide
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.SRPModel = Spherical;
aForceModel.SRP.Nominal_Sun = 149597870.691
Create Propagator aProp
aProp.FM = aForceModel
BeginMissionSequence
Propagate aProp(aSat){aSat.ElapsedDays = .2}
A ForceModel that uses a SPAD SRP File.
Create Spacecraft aSpacecraft;
aSpacecraft.DryMass
= 2000
aSpacecraft.SPADSRPFile = '..\data\vehicle\spad\SphericalModel.spo'
aSpacecraft.SPADSRPScaleFactor = 1;
Create ForceModel aFM;
aFM.SRP = On;
aFM.SRP.SRPModel = SPADFile
Create Propagator aProp;
aProp.FM = aFM;
BeginMissionSequence
469
Reference Guide
Propagator
Propagate aProp(aSpacecraft) {aSpacecraft.ElapsedDays = 0.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
470
Propagator
Reference Guide
Fields
Field
Description
CentralBody
The central body of propagation. This field has no effect for SPK or
Code500 propagators.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
EpochFormat
Only used for an SPK or Code500 propagator. The format of the
epoch contained in the StartEpoch field.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
Start Epoch
Enumeration
A1ModJulian, TAIModJulian, UTCModJulian, TTModJulian, TDBModJulian,
A1Gregorian, TAIGregorian, TTGregorian, UTCGregorian, TDBGregorian
set
A1ModJulian
N/A unless Mod Julian and in that case
Modified Julian Date
GUI, script
Only used for an SPK or Code500 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
Allowed Values
Access
Default Value
Units
Interfaces
StepSize
Resource reference
Celestial body
set
Earth
N/A
GUI, script
String
"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"
set
21545
N/A
GUI, script
The step size for an SPK or Code500 Propagator.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
Real
Real > 0
set
300
N/A
GUI, script
471
Reference Guide
Propagator
Field
Description
Type
Specifies the integrator or analytic propagator used to model time
evolution of spacecraft motion.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
Enumeration
PrinceDormand78, PrinceDormand45,
RungeKutta89,RungeKutta68,
RungeKutta56, BulirschStoer, AdamsBashforthMoulton, SPK, Code500
set
RungeKutta89
N/A
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.
472
Propagator
Reference Guide
Configuring Spacecraft SPK Kernels
To use an SPK-configured Propagator, you must add the SPK kernels to the Spacecraft and define the spacecraft'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 kernels via the GUI:
1.
2.
3.
4.
5.
On the Spacecraft dialog box, click the SPICE tab.
Under the SPK Files list, click Add.
Browse to locate and select the desired SPK file
Repeat to add all necessary SPK kernels
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
473
Reference Guide
Propagator
location of an SPK 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.
2.
Open the SPK propagator dialog box,
In the StartEpoch field., type FromSpacecraft or select FromSpacecraft from the dropdown 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}
474
Propagator
Reference Guide
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.
475
Reference Guide
Propagator
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}
Code500 Ephemeris-Configured Propagator
Description
A Code500 ephemeris-configured Propagator propagates a spacecraft by interpolating or stepping
along a user-provided Code500-format binary ephemeris file. You configure a Propagator to use a
Code500 ephemeris by setting the Type field to Code500. The Code500 ephemeris file is specified
on the Spacecraft.EphemerisName resource. The user controls 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 sequence, (i.e. myPropagator = yourPropagator ).
The Propagator CentralBody option is not applicable to the Code500 propagator and should not
be used with the Code500 propagator type. GMAT will automatically detect and use the central
body of the ephemeris file. The Propagate command should be used to traverse the ephemeris
file. GMAT will throw an error message and terminate when attempting to propagate outside the
bounds of the ephemeris file.
Code500 ephemeris files are binary-format files. As discussed in the EphemerisFile help, GMAT can
generate Code500 ephemeris files in both PC (little-endian) and UNIX (big-endian) binary format
(via EphemerisFile.OutputFormat). The Code500 propagator, however, only permits little-endian
formatted files.
See Also: Spacecraft, Propagate, EphemerisFile
Fields
The only Propagator fields applicable to the Code500 ephemeris propagator are EpochFormat,
StartEpoch, StepSize and Type.
476
Propagator
Reference Guide
Field
Description
EpochFormat
Only used for an SPK or Code500 propagator. Specifies format of
the epoch contained in the StartEpoch field.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
Start Epoch
Only used for an SPK or Code500 propagator. Specifies 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
Allowed Values
Access
Default Value
Units
Interfaces
StepSize
Enumeration
A1ModJulian, TAIModJulian, UTCModJulian, TTModJulian, TDBModJulian,
A1Gregorian, TAIGregorian, TTGregorian, UTCGregorian, TDBGregorian
set
A1ModJulian
N/A unless Mod Julian and in that case
Modified Julian Date
GUI, script
String
"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"
set
21545
N/A
GUI, script
The step size for an Code500 Propagator. GMAT will use this step
size when traversing the ephemeris file, regardless of the internal step
size of the ephemeris. GMAT will perform interpolation between
vectors on the file as needed.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
Real
Real > 0
set
300
N/A
GUI, script
477
Reference Guide
Propagator
Field
Description
Type
Specifies the integrator or analytic propagator used to model time
evolution of spacecraft motion. Specify Code500 for a Code500
ephemeris propagator.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
Enumeration
PrinceDormand78, PrinceDormand45,
RungeKutta89,RungeKutta68,
RungeKutta56, BulirschStoer, AdamsBashforthMoulton, SPK, Code500
set
RungeKutta89
N/A
GUI, script
GUI
To configure a Propagator from the GMAT GUI to use Code500 ephemeris files, select and open
a Propagator from the Resources tree. In the Integrator category select Code500 from the Type
drop-down box. This will display the Code500 propagator options dialog. There are four fields displayed for a Code500 propagator - 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. The CentralBody field is displayed to the user, but
is unused when the integrator type is Code500.
478
Propagator
Reference Guide
Remarks
There is currently no GUI option to assign the Code500 ephemeris file to the Spacecraft resource.
You must specify the Code500 ephemeris file on the Spacecraft.EphemerisName parameter via
script. The subsections below provide examples of how to do this.
Configuring Spacecraft Ephemeris Files
To use a Code500 ephemeris-configured Propagator, you must add the Code500 ephemeris file
to the Spacecraft. A sample spacecraft Code500 ephemeris, (sat_leo.ephem, in the data/vehicle/ephem/code500 directory) is distributed with GMAT. This sample file has a span of
4/20/2015 00:00:00 to 4/30/2015 00:00:00. An example of how to assign this ephemeris to a spacecraft is shown below. Relative paths are defined with respect to the GMAT bin directory of your
local installation.
Create Spacecraft aSpacecraft
aSpacecraft.EphemerisName = '../data/vehicle/ephem/code500/sat_leo.ephem'
BeginMissionSequence
A spacecraft may have only one Code500 ephemeris assigned. There is currently no GUI option to
add a Code500 ephemeris file to a spacecraft.
Configuring a Code500 Ephemeris Propagator
If you have assigned the ephemeris file to your spacecraft, configuring the propagator only requires
assigning the Code500 type and the desired step size on a Propagator resource. The central body
of propagation will be the central body of the the ephemeris file. If desired, you may also specify an
EpochFormat and StartEpoch on the propagator to specify an initial epoch from which to start
propagation. The same effect can be accomplished with an independent Propagate command (see
Propagate) to the desired starting epoch.
Create Propagator Code500Prop
Code500Prop.Type
= 'Code500'
Code500Prop.StepSize = 60.
BeginMissionSequence
The same remarks mentioned in the prior section on SPK propagators with regard to interaction
with the Propagate command and behavior near ephemeris boundaries also apply to the Code500
ephemeris propagator.
Examples
This example propagates a spacecraft using a Code500 ephemeris, defining the StartEpoch from
the spacecraft. The ephemeris file used in this example is included in the GMAT distribution at the
indicated location. The code below will run if you copy and paste it into a new GMAT script.
Create Spacecraft aSpacecraft
% Ephem file span is 4/20/2015 - 4/30/2015
479
Reference Guide
Propagator
aSpacecraft.EphemerisName = '../data/vehicle/ephem/code500/sat_leo.ephem'
aSpacecraft.DateFormat
= UTCGregorian
aSpacecraft.Epoch
= '22 Apr 2015 00:00:00.000'
Create Propagator Code500Prop
Code500Prop.Type
= 'Code500'
Code500Prop.StepSize
= 60.
Code500Prop.StartEpoch = 'FromSpacecraft'
Create ReportFile PropReport
PropReport.Filename
= 'EphemPropagator_Code500_ForwardProp.txt'
PropReport.WriteHeaders = True
BeginMissionSequence
While aSpacecraft.ElapsedDays <= 1
Propagate Code500Prop(aSpacecraft)
Report PropReport aSpacecraft.UTCGregorian aSpacecraft.TAIModJulian ...
aSpacecraft.X aSpacecraft.Y aSpacecraft.Z ...
aSpacecraft.VX aSpacecraft.VY aSpacecraft.VZ
EndWhile
An additional, more detailed, example of use of the Code500 ephemeris propagator is shown in
the Ex_Code500_EphemerisCompare.script file provided in the samples\Navigation
directory. This script generates a report showing the difference, in RIC coordinates, between the
orbits in two different Earth-centered Code500 ephemeris files.
480
Reference Guide
Receiver
Hardware that receives an RF signal.
Description
A GroundStation or Spacecraft resource needs a Receiver. A GroundStation resource, for example, needs to receive the RF signal from ground station user spacecraft. A Receiver is assigned
on the AddHardware list of an instance of a GroundStation or Spacecraft.
See Also: GroundStation, Antenna
Fields
Field
Description
PrimaryAntenna
Antenna resource used by Receiver or Spacecraft resource to receive a
signal
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
Antenna Object
Any valid Antenna object
set
None
N/A
script
Examples
Create and configure a Receiver object and attach it to a GroundStation.
Create Antenna DSNReceiverAntenna;
Create Receiver Receiver1;
Receiver1.PrimaryAntenna = DSNReceiverAntenna;
Create GroundStation DSN
DSN.AddHardware = {Receiver1};
BeginMissionSequence;
481
482
Reference Guide
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
Field
Description
Add
Allows a user to add any number of user-defined Variables, Arrays,
Strings or Object Parameters to a report file. To add multiple userdefined 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
Allowed Values
Access
Default Value
Units
Interfaces
ColumnWidth
Reference array
Any user-defined parameter. Ex. Variables, Arrays, Strings, or Object parameters
set
{DefaultSC.A1ModJulian,
DefaultSC.EarthMJ2000Eq.X}
N/A
GUI, script
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
Allowed Values
Access
Default Value
Units
Interfaces
Integer
Integer > 1
set
23
Characters
GUI, script
483
Reference Guide
ReportFile
Field
Description
Delimiter
When FixedWidth field is turned off, this field become active. The Delimiter field allows you to report data to a report file in Comma, Semicolon, Space and Tab delimited format.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
Filename
Allows the user to define the file path and file name for a report file.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
FixedWidth
Boolean
On, Off
set
On
N/A
GUI, script
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
Allowed Values
Access
Default Value
Units
Interfaces
484
String
Valid File Path and Name
set
ReportFile1.txt
N/A
GUI, script
Allows you to enable or disable Delimiter and ColumnWidth fields.
When this field is turned on, the Delimiter field is inactive and ColumnWidth field is active and can be used to vary the width of the data columns.
When FixedWidth field is turned off, the ColumnWidth field becomes
inactive and Delimiter field is active for use.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
LeftJustify
Enumeration
Comma, SemiColon, Space, Tab
set
When this field is active, then default is Space
N/A
GUI, script
Boolean
On, Off
set
On
N/A
GUI, script
ReportFile
Reference Guide
Field
Description
Maximized
Allows the user to maximize the ReportFile window. This field cannot be
modified in the Mission Sequence.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
Precision
Allows the user to set the number of significant digits of the data written
to a report.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
RelativeZOrder
Integer
Integer > 1
set
16
Same as variable being reported
GUI, script
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
Allowed Values
Access
Default Value
Units
Interfaces
Size
Boolean
true,false
set
false
N/A
script
Integer
Integer ≥ 0
set
0
N/A
script
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
Allowed Values
Access
Default Value
Units
Interfaces
Real array
Any Real number
set
[00]
N/A
script
485
Reference Guide
ReportFile
Field
Description
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
Allowed Values
Access
Default Value
Units
Interfaces
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
Allowed Values
Access
Default Value
Units
Interfaces
WriteHeaders
Boolean
True, False
set
True
N/A
GUI, script
This field specifies whether to write data to the report FileName.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
486
Real array
Any Real number
set
[00]
N/A
script
This field specifies whether to include headers that describe the variables
in a report file.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
WriteReport
Enumeration
All, Current, None
set
Current
N/A
GUI, script
Boolean
True, False
set
True
N/A
GUI, script
ReportFile
Reference Guide
Field
Description
ZeroFill
Allows zeros to be placed in data written to a report to match set precision.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
Boolean
On, Off
set
Off
N/A
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
487
Reference Guide
ReportFile
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
488
ReportFile
Reference Guide
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
options
Description
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.
489
Reference Guide
ReportFile
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}
490
ReportFile
Reference Guide
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
491
Reference Guide
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
492
ReportFile
Reference Guide
Simulator
Configures the generation of simulated tracking data measurements.
Description
A Simulator configures the generation of simulated tracking data measurements. These measurements can then be used by a BatchEstimatorInv resource as part of an estimation run.
The Simulator object requires specification of one or more instances of a TrackingFileSet resource
which identify the specific tracking data observation strands, data types, desired measurement corrections, and the output tracking data file name. Simulated data will be written in the GMAT Measurement Data (GMD) ASCII tracking data format. You must additionally specify a time span for
the simulation run and a time interval between simulated observations. Simulated observations are
only generated when a tracking strand meets the visibility constraints of all objects in the strand
(for example, the observation must be above the ground station minimum elevation mask). Additionally, you must configure and specify an instance of a Propagator for the simulator. Finally, you
can choose to add random Gaussian white noise to the generated measurements or to generate
measurements without noise. If the Simulator.AddNoise option is set to On, noise, with the standard deviation specified on each measurement strand’s GroundStation.ErrorModel, is added to
the measurements.
See Also: TrackingFileSet, RunEstimator
Fields
Field
Description
AddData
A list of one or more TrackingFileSets
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
AddNoise
TrackingFileSet object
Any valid TrackingFileSet object
set
None
N/A
script
If true, adds noise to simulated observations
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
Boolean
true, false, on, off
set
false
N/A
script
493
Reference Guide
Simulator
Field
Description
EpochFormat
Epoch format of both the initial and final epoch
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
InitialEpoch
The initial (start) epoch of the data simulation span. In the GMAT script,
the EpochFormat field needs to be set before this field is set.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
FinalEpoch
Access
Default Value
Units
Interfaces
Modified Julian: 6116.0 <= Epoch <= 58127.5
set
'21545'
N/A
script
STRING_TYPE
Gregorian: 04 Oct 1957 12:00:00.000 <= Epoch
<= 28 Feb 2100 00:00:00.000
Modified Julian: 6116.0 <= Epoch <= 58127.5
set
'21545'
N/A
script
Specifies time step in seconds between two consecutive simulated observations
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
494
STRING_TYPE
Gregorian: 04 Oct 1957 12:00:00.000 <= Epoch
<= 28 Feb 2100 00:00:00.000
The final (ending) epoch of the data simulation span. In the GMAT script,
the EpochFormat field needs to be set before this field is set.
Data Type
Allowed Values
MeasurementTimeStep
STRING_TYPE
A1ModJulian, TAIModJulian, UTCModJulian,
TTModJulian, TDBModJulian, A1Gregorian,
TAIGregorian, TTGregorian, UTCGregorian,
TDBGregorian
set
TAIModJulian
N/A
script
Real
Real > 0
set
60
seconds
script
Simulator
Reference Guide
Field
Description
Propagator
Name of Propagator object used for calculation
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
Propagator Object
Any valid Propagator object
set
None
N/A
script
Remarks
Interactions
Resource
Description
TrackingMust be created in order to tell the Simulator resource, via the AddData field,
FileSet
re- which data types will be simulated and to specify the name of the output tracking
source
data file (via FileName)
Propagator
resource
Used by GMAT to generate the simulated orbit
RunSimula- Must use the RunSimulator command to actually create the data defined by the
tor command Simulator resource
Examples
The example below illustrates using the simulator to generate DSN range measurements. This example is more detailed than usual as it can actually be run to produce a file, simData.gmd, that
contains a single range measurement for a fictional DSN ground station. For a more comprehensive
example of simulating measurements, see the Simulate DSN Range and Doppler Data tutorial.
%Create and Configure Spacecraft
Create Spacecraft SimSat;
GMAT SimSat.DateFormat = UTCGregorian;
GMAT SimSat.Epoch = '19 Aug 2015 00:00:00.000';
GMAT SimSat.X
= -126544963;
GMAT SimSat.Y
= 61978518;
GMAT SimSat.Z
= 24133225;
GMAT SimSat.VX
= -13.789;
GMAT SimSat.VY
= -24.673;
GMAT SimSat.VZ
= -10.662;
GMAT SimSat.AddHardware = {SatTransponder, SatTranponderAntenna};
%Create and configure RF hardware
Create Antenna SatTranponderAntenna DSNReceiverAntenna DSNTransmitterAntenna;
Create Transponder SatTransponder;
GMAT SatTransponder.PrimaryAntenna = SatTranponderAntenna;
Create Transmitter DSNTransmitter;
GMAT DSNTransmitter.PrimaryAntenna = DSNTransmitterAntenna;
GMAT DSNTransmitter.Frequency = 7200;
Create Receiver DSNReceiver;
495
Reference Guide
Simulator
GMAT DSNReceiver.PrimaryAntenna = DSNReceiverAntenna;
%Create and configure ground station and related error model
Create GroundStation DSN;
GMAT DSN.AddHardware = ...
{DSNTransmitter, DSNReceiver, DSNTransmitterAntenna, DSNReceiverAntenna};
GMAT DSN.ErrorModels = {DSNrange};
Create ErrorModel DSNrange;
GMAT DSNrange.Type = 'Range_RU';
GMAT DSNrange.NoiseSigma = 10;
%Define data types
Create TrackingFileSet simData;
GMAT simData.AddTrackingConfig = {{DSN,SimSat,DSN}, DSNRange};
GMAT simData.FileName
= {'simData.gmd'};
%
Create and configure the Simulator object
Create Propagator prop;
Create Simulator sim;
GMAT sim.AddData
GMAT sim.Propagator
GMAT sim.EpochFormat
GMAT sim.InitialEpoch
GMAT sim.FinalEpoch
GMAT sim.MeasurementTimeStep
GMAT sim.AddNoise
%
{simData};
prop;
UTCGregorian;
'19 Aug 2015 08:00:00.000';
'19 Aug 2015 08:00:01.000';
60;
On;
Mission Sequence - run the simulator.
BeginMissionSequence;
RunSimulator sim;
496
=
=
=
=
=
=
=
Reference Guide
SNOPT
The Sequential Quadratic Programming (SQP) optimizer, SNOPT
Description
The SNOPT optimizer is a SQP-based Nonlinear Programming solver developed by Stanford Business Software, Inc. It is a proprietary component that is not distritbuted with GMAT and must be
obtained from the vendor. SNOPT performs nonlinear constrained optimization and supports both
linear and nonlinear constraints. To use this solver, you must configure the solver options including convergence criteria, maximum iterations, among other options. In the mission sequence, you
implement an optimizer such as SNOPT 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: FminconOptimizer,Optimize,Vary, NonlinearConstraint, Minimize
Fields
Field
Description
MajorFeasibilityToler- Specifies how accurately the nonlinear constraints should be satisfied.
ance
Data Type
Real
Allowed Values
Real > 0
Access
set
Default Value
1e-5
Units
None
Interfaces
GUI, script
MajorIterationsLimit The maximum number of major iterations allowed. It is intended to guard
against an excessive number of linearizations of the constraints
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
MajorOptimalityTolerance
Integer
Integer > 0
set
1e-5
None
GUI, script
Specifies the final accuracy of the dual variables. See the SNOPT user
guide for further details.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
Real
Real > 0
set
1e-5
None
GUI, script
497
Reference Guide
SNOPT
Field
Description
OutputFileName
Contains the path and file name of the report file. This report contains data written by SNOPT regarding optimization progress and information.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
String
Any user-defined file name
set
SNOPT.out
N/A
GUI, script
OverrideSpecsFileVal- Flag to indicate if options settable in the GMAT script/GUI should overues
ride values set in the SNOPT Specs file. Note that if the specs file is not
found during initialization, GMAT configurations are applied even if the
OverrideSpecsFileValues field is set to false.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
ReportFile
Contains the path and file name of the report file. This report contains
data written by GMAT regarding optimization progress and information.
data Type
Allowed Values
Access
Default Value
Units
Interfaces
ReportStyle
String
Any user-defined file name
set
SNOPTSNOPT1.data
N/A
GUI,script
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
Allowed Values
Access
Default Value
Units
Interfaces
498
Boolean
true, false
set
true
None
GUI, script
String
Normal, Concise, Verbose, Debug
set
Normal
None
GUI, script
SNOPT
Reference Guide
Field
Description
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
Allowed Values
Access
Default Value
Units
Interfaces
SpecsFileName
File read by SNOPT to configure all settings of the optimizer. The GMAT
script/gui interface only supportsa small subset of the SNOPT configuration options. This file allows you to set any options supported by SNOPT.
This file is only loaded if it is found during initialization and selected values set on the file can be overwritten by the GMAT configuration by
OverrideSpecsFileValues = true. See the Remarks section for more
information.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
TotalIterationsLimit
Boolean
true, false
set
true
None
GUI, script
String
Any user-defined file name
set
SNOPT.spec
N/A
GUI, script
The maximum number of minor iterations allowed.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
Integer
Integer > 0
set
100000
None
GUI, script
GUI
The SNOPT dialog box allows you to specify properties of a SNOPT such as as maximum iterations, cost function tolerance, feasibility tolerance, choice of reporting options, and choice of whether
or not to use the central difference derivative method.
To create a SNOPT 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 SNOPT. This
will create a new SNOPT resource, SNOPT1. Double-click on SNOPT1 to bring up the SNOPT
dialog box shown below.
499
Reference Guide
SNOPT
Remarks
SNOPT Optimizer Version and Availability
GMAT currently uses SNOPT 7.2-12.2. This optimizer is not included as part of the nominal GMAT
installation and is only available if you have created and installed the SNOPT plug-in or obtained
SNOPT from the vendor.
SPECS File Configuration
The Specs file contains a list of options and values in the following general form:.
Begin options
Iterations limit 500
Minor feasibility tolerance 1.0e-7
Solution Yes
End options
The file starts with the keyword Begin and ends with End. The file is in free format. Each line
specifies a single option, using one or more items as follows:
1. A keyword (required for all options).
500
SNOPT
Reference Guide
2. A phrase (one or more words) that qualifies the keyword (only for some options).
3. A number that specifies an integer or real value (only for some options). Such numbers may be up
to 16 contiguous characters in Fortran 77’s I, F, E or D formats, terminated by a space or new line.
The items may be entered in upper or lower case or a mixture of both. Some of the keywords have
synonyms, and certain abbreviations are allowed, as long as there is no ambiguity. Blank lines and
comments may be used to improve readability. A comment begins with an asterisk (*) anywhere on a
line. All subsequent characters on the line are ignored. The Begin line is echoed to the Summary file.
For a complete list of SNOPT options, see the SNOPT user guide.
Configuring SNOPT for Effective Optimization
When using SNOPT, the Upper and Lower bounds in the Vary commands are required fields. By
setting these values appropriately for your problem, you reduce the likelihood that SNOPT will try
values that are unphysical or that can result in numerical singularities in the physical models. It is
important to set bounds carefully when using SNOPT.
Aditionally, SNOPT is quite senstive to scaling and care must be taken to provide acceptable values of AdditiveScaleFactor and MultiplicativeScaleFactor in the Vary commands. When using
SNOPT, derivatives are computed by SNOPT via the optimizer's built-in finite differencing. If an
optimization problem is not appropriately scaled, optimization may fail, or take an un-nesessarily
long time. Note that SNOPT has built-in scaling options that can be set via the Specs file and are
described in further detail in the SNOPT user guide.
Resource and Command Interactions
Warning
GMAT's Vary command is a generic interface designed to support many optimizers
and not all settings supported by the Vary command are supported by SNOPT. See
the Vary command documentation for details on the which Vary command settings are
supported by SNOPT.
The SNOPT 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
A simple mathematical optimization problem using SNOPT.
Create SNOPT NLP
GMAT NLP.ShowProgress = true
GMAT NLP.ReportStyle = Normal
GMAT NLP.ReportFile = output.report
GMAT NLP.MajorOptimalityTolerance = 0.001
GMAT NLP.MajorFeasibilityTolerance = 0.0001
GMAT NLP.MajorIterationsLimit = 456
501
Reference Guide
GMAT
GMAT
GMAT
GMAT
SNOPT
NLP.TotalIterationsLimit = 789012
NLP.OutputFileName = 'SNOPTName123.out'
NLP.SpecsFileName = 'SNOPT.spec'
NLP.OverrideSpecsFileValues = true
Create Variable X1 X2 J G
BeginMissionSequence
Optimize NLP {SolveMode = Solve, ExitMode = DiscardAndContinue}
% Vary the independent variables
Vary 'Vary X1' NLP(X1 = 0, {Perturbation = 0.0000001, Upper = 10, ...
Lower = -10, AdditiveScaleFactor = 0.0, ...
MultiplicativeScaleFactor = 1.0})
Vary 'Vary X2' NLP(X2 = 0, {Perturbation = 0.0000001, Upper = 10, ...
Lower = -10, AdditiveScaleFactor = 0.0, ...
MultiplicativeScaleFactor = 1.0})
% The cost function and Minimize command
J = ( X1 - 2 )^2 + ( X2 - 2 )^2
Minimize 'Minimize Cost (J)' NLP(J)
% Calculate constraint and use NonLinearConstraint command
GMAT G = X2 + X1
NonlinearConstraint NLP(G<=8)
EndOptimize
502
Reference Guide
SolarPowerSystem
A solar power system model
Description
The SolarPowerSystem models a solar power system including power generated as function of time
and distance from the sun, and includes shadow modeling by celestial bodies. The model allows you
to configure the power generated by the solar arrays, and the power required by the spacecraft bus.
For a complete descripton of how to configure all Resources required for electric propulsion modelling, see the Tutorial named Electric Propulsion
See Also ElectricTank, ElectricThruster, NuclearPowerSystem
Fields
Field
Description
AnnualDecayRate
The annual decay rate of the power system.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
BusCoeff1
Coefficient of power required by spacecraft bus.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
BusCoeff2
Real
0 <=Real <= 100
set
5
Percent/Year
GUI, script
Real
Real
set
0.3
kW
GUI, script
Coefficient of power required by spacecraft bus.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
Real
Real
set
0
kW*AU
GUI, script
503
Reference Guide
SolarPowerSystem
Field
Description
BusCoeff3
Coefficient of power required by spacecraft bus.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
EpochFormat
The epoch format for the PowerInitialEpoch field.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
InitialEpoch
Access
Default Value
Units
Interfaces
Real
Real >= 0
set
1.2
kW
GUI, script
The required margin between power left after power bus, and power used by the propulsion system.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
504
String
Valid GMAT Epoch consistent with
PowerInitialEpochFormat
set
01 Jan 2000 11:59:27.966
N/A
GUI, script
The maximum power generated at the PowerInitialEpoch.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
Margin
String
Valid Epoch format.
set
UTCGregorian
N/A
GUI, script
The initial epoch of the system used to define power system
elapsed lifetime.
Data Type
Allowed Values
InitialMaxPower
Real
Real
set
0
kw*AU2
GUI, script
Real
0 <=Real <= 100
set
5
Percent
GUI, script
SolarPowerSystem
Reference Guide
Field
Description
ShadowBodies
A list of celestial bodies for use in the shadow computation. A
body cannot be added more than once.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
ShadowModel
The model used for shadow computation in the Solar System Power Model.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
SolarCoeff1
Real
Real
set
1.32077
See Remarks
GUI, script
Coefficient of power created by solar power system.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
SolarCoeff3
String
None, DualCone
set
DualCone
N/A
GUI, script
Coefficient of power created by solar power system.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
SolarCoeff2
String List
A list of celestial bodies.
set
Earth
N/A
GUI, script
Real
Real
set
-0.10848
See Remarks
GUI, script
Coefficient of power created by solar power system.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
Real
Real
set
-0.11665
See Remarks
GUI, script
505
Reference Guide
SolarPowerSystem
Field
Description
SolarCoeff4
Coefficient of power created by solar power system.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
SolarCoeff5
Real
Real
set
0.10843
See Remarks
GUI, script
Coefficient of power created by solar power system.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
Real
Real
set
-0.01279
See Remarks
GUI, script
GUI
The GUI for the SolarPowerSystem is shown below.
Remarks
Computation of Base Power
The SolarPowerSystem models power degradation as a function of time. You must provide a power
system initial epoch, the power generated at that epoch, and an annual power decay rate. Additionally,
the AnnualDecayRate field models the power degredation on a per year basis. The base power is
computed using
506
SolarPowerSystem
Reference Guide
where "tau" is the power AnnualDecayRate, P_0 is InitialMaxPower, and "delta t" is the elapsed
time between the simulation epoch and InitialEpoch.
Computation of Bus Power
The power required by the spacecraft bus for all subsystems other than the propulsion system is
computed using
where A_Bus, B_Bus, and C_Bus are BusCoeff1, BusCoeff2, and BusCoeff3 respectively and r is
the distance from the Sun in Au.
Computation of Power Available for Propulsion
The solar power model scales the base power based on a polynomial function in terms of the solar
distance. Total power is compute using
where P_Sun is the percent sun ( full sun is 1.0, no sun is 0.0), r is the distance from the Sun in Au,
and C_1 is SolarCoeff1 and so on. Thrust power available for electric propulsion is finaly computed
using
Where "delta M" is power Margin.
Shadow Modelling and Discontinuities
Note that when modeling shadows for a solar power system, discontinuities in the force model can
occur when the power avialable for propulsion is less than a thruster's minimum useable power
setting. As a spacecraft passes from penumbra to umbra, and power avialable for thusting goes to
zero, thrust power causes thrust acceleration to discontinuously terminate, causing issues when using
adaptive step integrators. In this case, there are a few options. You can configure any itegrator to use
fixed step integration by setting the ErrorControl to None. Or you can configure the integrator
to continue propagating if a bad step, in this case a small discontinuity, occurs. See the Propagator
reference material for more information.
Examples
Create a SolarPowerSystem and attach it to a Spacecraft.
% Create the Solar Power System
Create SolarPowerSystem SolarPowerSystem1
%
Create a spacecraft an attach the Solar Power System
507
Reference Guide
SolarPowerSystem
Create Spacecraft DefaultSC
DefaultSC.PowerSystem = SolarPowerSystem1
BeginMissionSequence
For a complete descripton of how to configure all Resources required for electric propulsion modeling, see the Tutorial named Electric Propulsion.
508
Reference Guide
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.
Note
As of release R2015a, GMAT uses two separate solar system configurations for
core parts of the system. For propagation, GMAT uses the source specified by
SolarSystem.EphemerisSource and the CelestialBody properties configured on
each resource. For event location with the new ContactLocator and EclipseLocator
resources, GMAT always uses SPICE data for SolarSystem and CelestialBody properties. See ContactLocator, EclipseLocator, and CelestialBody for details.
See Also: CelestialBody, LibrationPoint, Barycenter, CoordinateSystem
Fields
Field
Description
DEFilename
The path and name of the DE file.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
EphemerisSource
String
Valid DE file
set
../data/planetary_ephem/de/
leDE1941.405
N/A
GUI, script
The ephemeris model for built-in celestial bodies.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
String
DE405, DE421, DE424, or SPICE
set
DE405
N/A
GUI, script
509
Reference Guide
Field
SolarSystem
Description
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
Allowed Values
Access
Default Value
Units
Interfaces
LSKFilename
The path and name of the SPK leap second kernel.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
PCKFilename
Access
Default Value
Units
Interfaces
String
Path to valid PCK planetary constants kernel
(.tpc)
set
../data/planetary_coeff/
pck00010.tpc
N/A
GUI, script
The path and name of the SPK orbit ephemeris kernel.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
510
String
Valid SPK leapsecond kernel
set
../data/time/naif0011.tls
N/A
GUI, script
The path and name of the PCK planetary constants kernel.
Data Type
Allowed Values
SPKFilename
Real
Real >= 0
set
0
N/A
GUI, script
String
Valid SPK ephemeris kernel (.bsp)
set
../data/planetary_ephem/spk/
DE405AllPlanets.bsp
N/A
GUI, script
SolarSystem
Reference Guide
Field
Description
UseTTForEphemeris
Flag to use Terrestrial Time (TT) as input to the orbital ephemeris
routines. When set to false, TDB is used.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
String
true,false
set
false
N/A
GUI, script
GUI
The SolarSystem dialog box allows you to configure global properties for solar system modelling.
The default configuration is illustrated above. Use Ephemeris Source 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.
511
Reference Guide
SolarSystem
Warning
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.
Additionally, when using DE as the EphemerisSource, modelling is with respect to
planetary system barcyenter. When using SPICE as the EphemerisSource, modelling
is with respect to the planet center.
If you select SPICE for Ephemeris Source, the SolarSystem dialog box reconfigures to disable
the Ephemeris Filename option, indicating that this is no longer used in this mission..
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.
512
SolarSystem
Reference Guide
• For general information on SPICE ephemeris files see the JPL NAIF site.
• For information on the SPK kernel named DE???AllPlanets.bsp distributed with GMAT,
see the Readme-DE???AllPlanets.txt files 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}
513
514
Reference Guide
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 Ballistic/Mass Properties
Spacecraft Epoch
Spacecraft Hardware
Spacecraft Navigation
Spacecraft Orbit State
Spacecraft Visualization Properties
515
516
Reference Guide
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
Field
Description
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
Allowed Values
Access
Default Value
Units
Interfaces
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
Allowed Values
Access
Default Value
Units
Interfaces
AngularVelocityZ
Real
-∞ < Real< ∞
set,get
0
deg/sec
GUI, script
Real
-∞ < Real< ∞
set,get
0
deg/sec
GUI, script
The z-component of Spacecraft body angular velocity expressed
in the inertial frame. AngularVelocityZ is used for the following
Attitude models: Spinner.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
Real
-∞ < Real< ∞
set,get
0
deg/sec
GUI, script
517
Reference Guide
Spacecraft Attitude
Field
Description
Attitude
The attitude mode for the Spacecraft.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
AttitudeConstraintType
The constraint type for resolving attitude ambiguity. The attitude is
computed such that the angle between the BodyConstraintVector and the constraint defined by AttitudeConstraintType is
minimized. A Velocity constraint uses the inertial velocity vector
expressed with respect to the AttitudeReferenceBody. An OrbitNormal constraint uses the orbit normal vector expressed with
respect to the AttitudeReferenceBody. AttitudeConstraintType is used for the following attitude models: NadirPointing.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
AttitudeCoordinateSystem
String
CoordinateSystem resource.
set
EarthMJ2000Eq
N/A
GUI, script
Path (optional) and name of CCSDS attitude ephemeris message
file. If a path is not provided, and GMAT does not find the file in
the current directory, then an error occurs and execution is halted.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
518
Enumeration
Velocity, OrbitNormal
set
OrbitNormal
N/A
GUI, script
The CoordinateSystem used in attitude computations. The AttitudeCoordinateSystem field is only used for the following attitude models: CoordinateSystemFixed.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
AttitudeFileName
String
CoordinateSystemFixed,
Spinner,
SpiceAttitude,
NadirPointing,
CCSDS-AEM, PrecessingSpinner
set
CoordinateSystemFixed
N/A
GUI, script
String
AEM File
set
N/A
N/A
GUI, script
Spacecraft Attitude
Reference Guide
Field
Description
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
Allowed Values
Access
Default Value
Units
Interfaces
AttitudeReferenceBody
The celestial body used to define nadir. AttitudeReferenceBody
is used for the following attitude models: NadirPointing.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
AttitudeSpiceKernelName
Resource
Celestial Body
set
Earth
N/A
GUI, script
SPK Kernels for Spacecraft attitude. SPK atttitude kernels have
extension ".BC". This field cannot be set in the Mission Sequence.
An empty list unloads all kernels of this type on the Spacecraft.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
BodyAlignmentVectorX
String
AngularVelocity, EulerAngleRates
set
AngularVelocity
N/A
GUI, script
String array
Array of attitude kernel files
set
empty array
N/A
GUI, script
The x-component of the alignment vector, expressed in the body
frame, to align with the opposite of the radial vector. BodyAlignmentVectorX is used for the following attitude models: NadirPointing.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
Real
-∞ < Real < ∞
set
1
N/A
GUI, script
519
Reference Guide
Spacecraft Attitude
Field
Description
BodyAlignmentVectorY
The y-component of the alignment vector, expressed in the body
frame, to align with the opposite of the radial vector. BodyAlignmentVectorY is used for the following attitude models: NadirPointing.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
BodyAlignmentVectorZ
The z-component of the alignment vector, expressed in the body
frame, to align with the opposite of the radial vector. BodyAlignmentVectorZ is used for the following attitude models: NadirPointing.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
BodyConstraintVectorX
Real
-∞ < Real < ∞
set
0
N/A
GUI, script
The y-component of the constraint vector, expressed in the body
frame. See NadirPointing description for further details. BodyConstraintVectorY is used for the following attitude models:
NadirPointing.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
520
Real
-∞ < Real < ∞
set
0
N/A
GUI, script
The x-component of the constraint vector, expressed in the body
frame. See NadirPointing description for further details. BodyConstraintVectorX is used for the following attitude models:
NadirPointing.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
BodyConstraintVectorY
Real
-∞ < Real < ∞
set
0
N/A
GUI, script
Real
-∞ < Real < ∞
set
0
N/A
GUI, script
Spacecraft Attitude
Reference Guide
Field
Description
BodyConstraintVectorZ
The z-component of the constraint vector, expressed in the body
frame. See NadirPointing description for further details. BodyConstraintVectorZ is used for the following attitude models:
NadirPointing.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
BodySpinAxisX
The x-component of the spin axis, expressed in the body frame.
BodySpinAxisX is used for the following attitude models: PrecessingSpinner.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
BodySpinAxisY
Real
-∞ < Real < ∞
set
0
N/A
GUI, script
The y-component of the spin axis, expressed in the body frame.
BodySpinAxisY is used for the following attitude models: PrecessingSpinner.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
BodySpinAxisZ
Real
-∞ < Real < ∞
set
1
N/A
GUI, script
Real
-∞ < Real < ∞
set
0
N/A
GUI, script
The z-component of the spin axis, expressed in the body frame.
BodySpinAxisZ is used for the following attitude models: PrecessingSpinner.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
Real
-∞ < Real < ∞
set
1
N/A
GUI, script
521
Reference Guide
Spacecraft Attitude
Field
Description
DCM11
Component (1,1) of the Direction Cosine Matrix. DCM11 is used
for the following Attitude models: Spinner.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
DCM12
Component (1,2) of the Direction Cosine Matrix. DCM12 is used
for the following Attitude models: Spinner.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
DCM13
Real
-1 <= Real <=1
set,get
0
N/A
GUI, script
Component (2,2) of the Direction Cosine Matrix. DCM22 is used
for the following Attitude models: Spinner.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
522
Real
-1 <= Real <=1
set,get
0
N/A
GUI, script
Component (2,1) of the Direction Cosine Matrix. DCM21 is used
for the following Attitude models: Spinner.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
DCM22
Real
-1 <= Real <=1
set,get
0
N/A
GUI, script
Component (1,3) of the Direction Cosine Matrix. DCM13 is used
for the following Attitude models: Spinner.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
DCM21
Real
-1 <= Real <=1
set,get
1
N/A
GUI, script
Real
-1 <= Real <=1
set,get
1
N/A
GUI, script
Spacecraft Attitude
Reference Guide
Field
Description
DCM23
Component (2,3) of the Direction Cosine Matrix. DCM23 is used
for the following Attitude models: Spinner.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
DCM31
Component (3,1) of the Direction Cosine Matrix. DCM31 is used
for the following Attitude models: Spinner.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
DCM32
Real
-1 <= Real <=1
set,get
1
N/A
GUI, script
Component (3,3) of the Direction Cosine Matrix. DCM33 is used
for the following Attitude models: Spinner.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
EulerAngle1
Real
-1 <= Real <=1
set,get
0
N/A
GUI, script
Component (3,2) of the Direction Cosine Matrix. DCM32 is used
for the following Attitude models: Spinner.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
DCM33
Real
-1 <= Real <=1
set,get
0
N/A
GUI, script
Real
-1 <= Real <=1
set,get
1
N/A
GUI, script
The value of the first Euler angle. EulerAngle1 is used for the
following Attitude models: Spinner.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
Real
-∞ < Real < ∞
set,get
0
deg.
GUI, script
523
Reference Guide
Spacecraft Attitude
Field
Description
EulerAngle2
The value of the second Euler angle. EulerAngle2 is used for the
following Attitude models: Spinner.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
EulerAngle3
The value of the third Euler angle. EulerAngle3 is used for the
following Attitude models: Spinner.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
EulerAngleRate1
Real
-∞ < Real < ∞
set,get
1
deg./sec.
GUI, script
The value of the third Euler angle rate. EulerAngleRate3 is used
for the following Attitude models: Spinner.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
524
Real
-∞ < Real < ∞
set,get
0
deg./sec.
GUI, script
The value of the second Euler angle rate. EulerAngleRate2 is
used for the following Attitude models: Spinner.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
EulerAngleRate3
Real
-∞ < Real < ∞
set,get
0
deg.
GUI, script
The value of the first Euler angle rate. EulerAngleRate1 is used
for the following Attitude models: Spinner.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
EulerAngleRate2
Real
-∞ < Real < ∞
set,get
0
deg.
GUI, script
Real
-∞ < Real < ∞
set,get
1
deg./sec.
GUI, script
Spacecraft Attitude
Reference Guide
Field
Description
FrameSpiceKernelName
SPK Kernels for Spacecraft body frame. SPK Frame kernels have
extension ".TF". This field cannot be set in the Mission Sequence.
An empty list unloads all kernels of this type on the Spacecraft.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
EulerAngleSequence
The Euler angle sequence used for Euler angle input and output..
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
InitialPrecessionAngle
Real
-∞ < Real < ∞
set
0
deg.
GUI, script
The initial attitude spin angle. InitialSpinAngle is used for the
following attitude models: PrecessingSpinner.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
NAIFIdReferenceFrame
String
123,231,312,132,321,213,121,
232,313,131,323,212
set
321
N/A
GUI, script
The initial precession angle. InitialPrecessionAngle is used for
the following attitude models: PrecessingSpinner.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
InitialSpinAngle
String array
Array of .tf files.
set
emtpy array
N/A
GUI, script
Real
-∞ < Real < ∞
set
0
deg.
GUI, script
The Id of the spacecraft body frame used in SPICE kernels.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
Integer
-∞ < Integer < ∞
set
-9000001
N/A
GUI, script
525
Reference Guide
Spacecraft Attitude
Field
Description
NutationAngle
The attitude nutation angle. NutationAngle is used for the following attitude models: PrecessingSpinner.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
NutationReferenceVectorX
The x-component of the nutation reference vector, expressed in
the inertial frame. NutationReferenceVectorX is used for the
following attitude models: PrecessingSpinner.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
NutationReferenceVectorY
Real
-∞ < Real < ∞
set
0
N/A
GUI, script
The z-component of the nutation reference vector, expressed in
the inertial frame. NutationReferenceVectorZ is used for the
following attitude models: PrecessingSpinner.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
526
Real
-∞ < Real < ∞
set
0
N/A
GUI, script
The y-component of the nutation reference vector, expressed in
the inertial frame. NutationReferenceVectorY is used for the following attitude models: PrecessingSpinner.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
NutationReferenceVectorZ
Real
-∞ < Real < ∞
set
15
deg.
GUI, script
Real
-∞ < Real < ∞
set
1
N/A
GUI, script
Spacecraft Attitude
Reference Guide
Field
Description
MRP1
The value of the first modified Rodrigues parameter. MRP1 is used
for the following Attitude models: Spinner.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
MRP2
The value of the second modified Rodrigues parameter. MRP2 is
used for the following Attitude models: Spinner.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
MRP3
Real
-∞ < Real < ∞
set,get
0
dimensionless
GUI, script
The value of the second modified Rodrigues parameter. MRP2 is
used for the following Attitude models: Spinner.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
PrecessionRate
Real
-∞ < Real < ∞
set,get
0
dimensionless
GUI, script
Real
-∞ < Real < ∞
set,get
0
dimensionless
GUI, script
The rate of attitude precession. InitialPrecessionAngle is used
for the following attitude models: PrecessingSpinner.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
Real
-∞ < Real < ∞
set
0
deg./s
GUI, script
527
Reference Guide
Spacecraft Attitude
Field
Description
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
Allowed Values
Access
Default Value
Units
Interfaces
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
Allowed Values
Access
Default Value
Units
Interfaces
Q3
Real
-∞ < Real < ∞
set,get
0
dimensionless
GUI, script
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
Allowed Values
Access
Default Value
Units
Interfaces
528
Real
-∞ < Real < ∞
set,get
0
dimensionless
GUI, script
Real
-∞ < Real < ∞
set,get
0
dimensionless
GUI, script
Spacecraft Attitude
Reference Guide
Field
Description
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
Allowed Values
Access
Default Value
Units
Interfaces
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
Allowed Values
Access
Default Value
Units
Interfaces
SCClockSpiceKernelName
Real array
Real array (length four)
set,get
[0 0 0 1];
dimensionless
GUI, script
SPK Kernels for spacecraft clock. SPK clock kernels have extension ".TSC". This field cannot be set in the Mission Sequence. An
empty list unloads all kernels of this type on the Spacecraft. An
empty list unloads all kernels of this type on the Spacecraft.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
SpinRate
Real
-∞ < Real < ∞
set,get
1
dimensionless
GUI, script
String array
Array of .tsc file names
set,get
empty array
N/A
GUI, script
The attitude spin rate. SpinRate is used for the following attitude
models: PrecessingSpinner.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
Real
-∞ < Real < ∞
set
10
deg./s
GUI, script
529
Reference Guide
Spacecraft Attitude
Remarks
Overview of Availble Attitude Models
GMAT supports many attitude models including the following: CoordinateSystemFixed, SpiceAttitude, NadirPointing, CCSDS-AEM, PrecessingSpinner, and Spinner (we recommend using
thew new PrecessingSpinner model instead of Spinner). 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
reference tables above, and the detailed examples for each model type below, describe which fields
are used for each model.
Note
GMAT attitude parameterizations such as the DCM rotate from inertial to body.
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
aSpacecraft.Q2
aSpacecraft.Q3
aSpacecraft.Q4
=
=
=
=
0.5
0.5
0.5
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 that rotate from the x,
y, and z inertial axes to the x, y, and z body 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
530
Spacecraft Attitude
Reference Guide
aSpacecraft.DCM21
aSpacecraft.DCM22
aSpacecraft.DCM23
aSpacecraft.DCM31
aSpacecraft.DCM32
aSpacecraft.DCM33
=
=
=
=
=
=
0
1
0
0
0
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.
531
Reference Guide
Spacecraft Attitude
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'
532
Spacecraft Attitude
Reference Guide
Create ForceModel Propagator1_ForceModel
Create Propagator Propagator1
Propagator1.FM
= Propagator1_ForceModel
Propagator1.MaxStep
= 10
Create CoordinateSystem
attCoordSys.Origin
=
attCoordSys.Axes
=
attCoordSys.XAxis
=
attCoordSys.YAxis
=
attCoordSys.Primary
=
attCoordSys.Secondary =
attCoordSys
Earth
ObjectReferenced
V
N
Earth
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. We recommend using the newer PrecessingSpinner model instead of Spinner, and
this model is maintained primarily for backwards compatibility. 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.
533
Reference Guide
Spacecraft Attitude
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.Origin
=
attCoordSys.Axes
=
attCoordSys.XAxis
=
attCoordSys.YAxis
=
attCoordSys.Primary
=
attCoordSys.Secondary =
attCoordSys
Earth
ObjectReferenced
V
N
Earth
aSat
Create OrbitView OrbitView1;
OrbitView1.Add
= {aSat, Earth}
OrbitView1.ViewPointReference = Earth
OrbitView1.ViewPointVector
= [ 30000 0 0 ]
BeginMissionSequence
534
Spacecraft Attitude
Reference Guide
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.
535
Reference Guide
Spacecraft Attitude
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'
536
Spacecraft Attitude
Reference Guide
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}
Nadir Pointing Model
The NadirPointing attitude mode configures the attitude of a spacecraft to point a specified vector
in the spacecraft body system in the nadir direction. The ambiguity in angle about the nadir vector
is resolved by minimizing the angle between two constraint vectors. Note: the nadir pointing mode
points the attitude in the negative radial direction (not opposite the planetodetic normal).
To configure which axis points to nadir, set the AttitudeReferenceBody field to the desired celestial
body and define the body components of the alignment vector using the BodyAlignmentVector
fields. To configure the constraint, set the AttitudeConstraintType field to the desired constraint
type, and define the body components of the constraint using the BodyConstraintVector fields.
GMAT supports two constraint types, OrbitNormal and Velocity, and in both cases the vectors
are constructed using the inertial spacecraft state with respect to the AttitudeReferenceBody.
Warning
Attitude rates are not computed for the NadirPointing model. If you perform a computation that requires attitude rate information when using the NadirPointing mode,
GMAT will throw an error message and execution will stop. Similarly, if the definitions
of the BodyAlignmentVector and BodyConstraintVector fields result in an undefined attitude, an error message is thrown and execution will stop.
537
Reference Guide
Spacecraft Attitude
The script example below shows how to configure a Spacecraft to use an Earth NadirPointing
attitude system where the body y-axis points nadir and the angle between the body x-axis and the
orbit normal vector is a minimum.
Create Spacecraft aSat;
GMAT aSat.Attitude
GMAT aSat.AttitudeReferenceBody
GMAT aSat.AttitudeConstraintType
GMAT aSat.BodyAlignmentVectorX =
GMAT aSat.BodyAlignmentVectorY =
GMAT aSat.BodyAlignmentVectorZ =
GMAT aSat.BodyConstraintVectorX =
GMAT aSat.BodyConstraintVectorX =
GMAT aSat.BodyConstraintVectorX =
= NadirPointing;
= Earth
= OrbitNormal
0
1
0
1
0
0
Create ForceModel Propagator1_ForceModel
Create Propagator Propagator1
Propagator1.FM
= Propagator1_ForceModel
Propagator1.MaxStep
= 10
Create OrbitView OrbitView1;
OrbitView1.Add
= {aSat, Earth}
OrbitView1.ViewPointReference = Earth
OrbitView1.ViewPointVector
= [ 30000 0 0 ]
BeginMissionSequence
538
Spacecraft Attitude
Reference Guide
Propagate Propagator1(aSat) {aSat.ElapsedSecs = 12000.0}
CCSDS Attitude Ephemeris Message
The CCSDS Attitude Ephemeris Message (AEM) is an ASCII standard for attitude ephemerides documented in “ATTITUDE DATA MESSAGES” RECOMMENDED STANDARD CCSDS 504.0B-1. GMAT supports some, but not all, of the attitude messages defined in the standard. According
to the CCSDS AEM specification, “The set of attitude data messages described in this Recommended Standard is the baseline concept for attitude representation in data interchange applications that
are cross-supported between Agencies of the CCSDS.” Additionally, the forward of the standard
states “Derived Agency standards may implement only a subset of the optional features allowed
by the Recommended Standard and may incorporate features not addressed by this Recommended
Standard. See the details below for supported keyword types and details for creating AEM files that
GMAT can use for attitude modelling.
An AEM file must have the format illustrated below described in Table 4-1 of the standard. The
header section contains high level information on the version, originator, and date. The body of the
file is composed of paired blocks of Metadata and data. The Metadata sections contain information
on the data such as the first and last epoch of the block, the time system employed, the reference
frames, the attitude type (quaternion, Euler Angle, etc.) and many other items documented in later
sections. The data sections contain lines of epoch and attitude data.
539
Reference Guide
Spacecraft Attitude
An example CCSDS AEM file is shown below
CCSDS_AEM_VERS = 1.0
CREATION_DATE = 2002-11-04T17:22:31
ORIGINATOR = NASA/JPL
META_START
COMMENT This file was produced by M.R. Somebody, MSOO NAV/JPL, 2002 OCT 04.
COMMENT It is to be used for attitude reconstruction only.
COMMENT The relative accuracy of these attitudes is 0.1 degrees per axis.
OBJECT_NAME = MARS GLOBAL SURVEYOR
OBJECT_ID = 1996-062A
CENTER_NAME = mars barycenter
REF_FRAME_A = EME2000
REF_FRAME_B = SC_BODY_1
ATTITUDE_DIR = A2B
TIME_SYSTEM = UTC
START_TIME = 1996-11-28T21:29:07.2555
USEABLE_START_TIME = 1996-11-28T22:08:02.5555
USEABLE_STOP_TIME = 1996-11-30T01:18:02.5555
STOP_TIME = 1996-11-30T01:28:02.5555
ATTITUDE_TYPE = QUATERNION
QUATERNION_TYPE = LAST
INTERPOLATION_METHOD = hermite
INTERPOLATION_DEGREE = 7
META_STOP
DATA_START
1996-11-28T21:29:07.2555 0.56748 0.03146 0.45689 0.68427
1996-11-28T22:08:03.5555 0.42319 -0.45697 0.23784 0.74533
1996-11-28T22:08:04.5555 -0.84532 0.26974 -0.06532 0.45652
< intervening data records omitted here >
1996-11-30T01:28:02.5555 0.74563 -0.45375 0.36875 0.31964
DATA_STOP
META_START
540
Spacecraft Attitude
Reference Guide
COMMENT This block begins after trajectory correction maneuver TCM-3.
OBJECT_NAME = mars global surveyor
OBJECT_ID = 1996-062A
CENTER_NAME = MARS BARYCENTER
REF_FRAME_A = EME2000
REF_FRAME_B = SC_BODY_1
ATTITUDE_DIR = A2B
TIME_SYSTEM = UTC
START_TIME = 1996-12-18T12:05:00.5555
USEABLE_START_TIME = 1996-12-18T12:10:00.5555
USEABLE_STOP_TIME = 1996-12-28T21:23:00.5555
STOP_TIME = 1996-12-28T21:28:00.5555
ATTITUDE_TYPE = QUATERNION
QUATERNION_TYPE = LAST
META_STOP
DATA_START
1996-12-18T12:05:00.5555 -0.64585 0.018542 -0.23854 0.72501
1996-12-18T12:10:05.5555 0.87451 -0.43475 0.13458 -0.16767
1996-12-18T12:10:10.5555 0.03125 -0.65874 0.23458 -0.71418
< intervening records omitted here >
1996-12-28T21:28:00.5555 -0.25485 0.58745 -0.36845 0.67394
DATA_STOP
CCSDS files require many keywords and fields, some are required for all file types, others are Situationally Required (SR) depending upon the type of file (i.e. If ATTITUDE_TYPE = QUATERNION, then QUATERNION_TYPE must be included). The tables below describe GMAT’s implementation starting with header keywords
Keyword
Re- Description and Supported Values
quired
CCSDS_AEM_VERS Y
Format version in the form of ‘x.y’, where ‘y’ is incremented for
corrections and minor changes, and ‘x’ is incremented for major
changes. This particular line must be the first non-blank line in the
file. In GMAT the version must be set to 1.0. If the version is not
set to a supported version, then GMAT throws an exception.
Example:
CCSDS_AEM_VERS =1.0
COMMENT
N
Comments (allowed after AEM version number and
META_START and before a data block of ephemeris lines). Each
comment line shall begin with this keyword. GMAT does not use
this field.
541
Reference Guide
Spacecraft Attitude
Keyword
Re- Description and Supported Values
quired
CREATION_DATE
Y
File creation date/time in one of the following formats:
YYYY-MM-DDThh:mm:ss[.d?d] or YYYY-DDDThh:mm:ss[.d?
d] where ‘YYYY’ is the year, ‘MM’ is the two-digit month, ‘DD’
is the two-digit day, ‘DDD’ is the threedigit day of year, ‘T’ is constant, ‘hh:mm:ss[.d?d]’ is the UTC time in hours, minutes, seconds,
and optional fractional seconds. As many ‘d’ characters to the right
of the period as required may be used to obtain the required precision. All fields require leading zeros. GMAT does not use this field.
ORIGINATOR
Y
Creating agency (value should be specified in an ICD). GMAT
does not use this field.
MetaData Keywords are described in the table below.
Keyword
Re- Description and Supported Values
quired
META_START
Y
The AEM message contains both metadata and attitude ephemeris
data; this keyword is used to delineate the start of a metadata block
within the message (metadata are provided in a block, surrounded
by ‘META_START’ and ‘META_STOP’ markers to facilitate file
parsing). This keyword must appear on a line by itself.
COMMENT
N
Comments allowed only at the beginning of the Metadata section.
Each comment line shall begin with this keyword. GMAT does
not use this.
Example:
COMMENT This is a comment
OBJECT_NAME
Y
Spacecraft name of the object corresponding to the attitude data to be given. There is no CCSDS-based restriction on the value
for this keyword, but it is recommended to use names from the
SPACEWARN Bulletin, which include the Object name and international designator of the participant.
Example:
OBJECT_NAME = EUTELSAT
Note: GMAT does not use this field. In GMAT, you associate a file
with a particular spacecraft by configuring a particular spacecraft
to use the file as shown below.
Create Spacecraft aSat
aSat.Attitude = CCSDS-AEM
aSat.AttitudeFileName = myFile.aem
542
Spacecraft Attitude
Reference Guide
Keyword
Re- Description and Supported Values
quired
OBJECT_ID
Y
Spacecraft identifier of the object corresponding to the attitude
data to be given. See the AEM specification for recommendations
for spacecraft Ids. GMAT does not use this field.
CENTER_NAME
N
Origin of reference frame, which may be a natural solar system
body (planets, asteroids, comets, and natural satellites), including
any planet barycenter or the solar system barycenter, or another
spacecraft (in this the value for ‘CENTER_NAME’ is subject to
the same rules as for ‘OBJECT_NAME’). There is no CCSDSbased restriction on the value for this keyword, but for natural
bodies it is recommended to use names from the NASA/JPL Solar
System Dynamics Group . GMAT does not use this field.
REF_FRAME_A
Y
The name of the reference frame specifying one frame of the
transformation, whose direction is specified using the keyword
ATTITUDE_DIR. The full set of values is enumerated in annex
A of the AEM standard, with an excerpt provided in the ‘Values /
Examples’ column.
In GMAT, REF_FRAME_A can be any of the following and must
be different than REF_FRAME_B: EME2000, SC_BODY_1
Example:
REF_FRAME_A = EME2000
REF_FRAME_A = SC_Body_1
REF_FRAME_B
Y
The name of the reference frame specifying one frame of the
transformation, whose direction is specified using the keyword
ATTITUDE_DIR. The full set of values is enumerated in annex
A of the AEM standard, with an excerpt provided in the ‘Values /
Examples’ column.
In GMAT, REF_FRAME_B can be any of the following and must
be different than REF_FRAME_A: EME2000, SC_BODY_1
Example:
REF_FRAME_A = EME2000
REF_FRAME_A = SC_Body_1
543
Reference Guide
Spacecraft Attitude
Keyword
Re- Description and Supported Values
quired
ATTITUDE_DIR
Y
Rotation direction of the attitude specifying from which frame
the transformation is to: A2B specifies a transformation from the
REF_FRAME_A to the REF_FRAME_B; B2A specifies a transformation from the REF_FRAME_B to the REF_FRAME_A.
Examples:
ATTITUDE_DIR = A2B
ATTITUDE_DIR = B2A
TIME_SYSTEM
Y
Time system used for both attitude ephemeris data and metadata.
GMAT supports the following options: UTC
Example:
TIME_SYSTEM = UTC
START_TIME
Y
Start of TOTAL time span covered by attitude ephemeris data immediately following this metadata block. The START_TIME time
tag at a new block of attitude ephemeris data must be equal to
or greater than the STOP_TIME time tag of the previous block.
See the CREATION_DATE specification for detailed information on time formats. Note: precision in the seconds place is only
preserved to a few microseconds.
Example:
START_TIME = 1996-12-18T14:28:15.117
USEABLE_
N
START_TIME, USEABLE_ STOP_TIME
Optional start and end of USEABLE time span covered by attitude ephemeris data immediately following this metadata block.
To allow for proper interpolation near the ends of the attitude
ephemeris data block, it may be necessary, depending upon the
interpolation method to be used, to utilize these keywords with
values within the time span covered by the attitude ephemeris data records as denoted by the START/STOP_TIME time tags. If
this is provided, GMAT only uses data in the USEABLE timespan for interpolation. If it is not provided, GMAT uses the data in
the START_TIME/STOP_TIME segment for interpolation. See
the CREATION_DATE specification for detailed information on
time formats.
Example:
USEABLE_ START_TIME = 1996-12-18T14:28:15.117
USEABLE_ STOP_TIME = 1996-12-18T14:28:15.117
544
Spacecraft Attitude
Reference Guide
Keyword
Re- Description and Supported Values
quired
STOP_TIME
Y
End of TOTAL time span covered by the attitude ephemeris data immediately following this metadata block. The STOP_TIME
time tag for the block of attitude ephemeris data must be equal
to or less than the START_TIME time tag of the next block. See
the CREATION_DATE specification for detailed information on
time formats. Note: precision in the seconds place is only preserved to a few microseconds.
Example:
STOP_TIME = 1996-12-18T14:28:15.117
ATTITUDE_TYPE
Y
The format of the data lines in the message. GMAT supports the
following types
ATTITUDE_TYPE = QUATERNION
ATTITUDE_TYPE = EULER_ANGLE
QUATERNION_TYPESR
The placement of the scalar portion of the quaternion (QC) in
the attitude data. This keyword is only used if ATTITUDE_TYPE
denotes quaternion and in that case the field is required.
Example:
QUATERNION_TYPE = FIRST
QUATERNION_TYPE = LAST
EULER_ROT_SEQ
SR
The rotation sequence of the Euler angles that rotate from
REF_FRAME_A to REF_FRAME_B, or vice versa, as specified
using the ATTITUDE_DIR keyword. This keyword is only used
if ATTITUDE_TYPE denotes EulerAngles and in that case the
field is required.
Example:
EULER_ROT_SEQ = 321
RATE_FRAME
N
GMAT does not use this field.
545
Reference Guide
Spacecraft Attitude
Keyword
Re- Description and Supported Values
quired
INTERPOLATION
_METHOD
N
Recommended interpolation method for attitude ephemeris
data in the block immediately following this metadata
block. Note. GMAT uses spherical linear interpolation when
ATTITUDE_TYPE = QUATERNION. GMAT uses lagrange interpolation for ATTITUDE_TYPE = EULER_ANGLE.
Examples:
INTERPOLATION _METHOD = LINEAR
INTERPOLATION _METHOD = LAGRANGE
INTERPOLATION
_DEGREE
SR
Recommended interpolation degree for attitude ephemeris data in the block immediately following this metadata block. It
must be an integer value. This keyword must be used if the
‘INTERPOLATION_METHOD’ keyword is used. The field is
only used for Lagrange Interpolation and in that case the value
must be between 0 and 9. In the case order is zero for Lagrange
interpolation, no interpolation is performed, and the attitude returned is the value immediately before the requested epoch.
Example:
INTERPOLATION _DEGREE = 7
META_STOP
Y
The end of a metadata block within the message. The AEM message contains both metadata and attitude ephemeris data; this
keyword is used to delineate the end of a metadata block within the message (metadata are provided in a block, surrounded
by ‘META_START’ and ‘META_STOP’ markers to facilitate file
parsing). This keyword must appear on a line by itself.
Data Keywords are described in the table below.
546
Keyword
Re- Description and Supported Values
quired
DATA_START
Y
The start of an attitude data block within the message. The
AEM message contains both metadata and attitude ephemeris
data; this keyword is used to delineate the start of a data block
within the message (data are provided in a block, surrounded
by ‘DATA_START’ and ‘DATA_STOP’ markers to facilitate file
parsing). This keyword must appear on a line by itself.
DATA_STOP
Y
The end of an attitude data block within the message. The AEM
message contains both metadata and attitude ephemeris data; this
keyword is used to delineate the end of a data block within the message (data are provided in a block, surrounded by ‘DATA_START’
and ‘DATA_STOP’ markers to facilitate file parsing). This keyword must appear on a line by itself.
Spacecraft Attitude
Reference Guide
Keyword
Re- Description and Supported Values
quired
QUATERNION
SR
Required when ATTITUDE_TYPE = QUATERNION. The
general format of a quaternion data line is: Epoch, QC, Q1, Q2,
Q3 or Epoch, Q1, Q2, Q3, QC
Example:
2000-01-01T11:59:28.000
0.92404936
EULER ANGLE
SR
0.195286
-0.079460
0.3188764
Required when ATTITUDE_TYPE = EULER_ANGLE. The
general format of an Euler angle data line is: Epoch, X_Angle,
Y_Angle, Z_Angle.
Example:
2000-001T11:59:28.000 35.45409 -15.74726 18.803877
Propagate a spacecraft's attitude using a CCSDS AEM file
Create Spacecraft aSat ;
GMAT aSat.Attitude = CCSDS-AEM;
GMAT aSat.AttitudeFileName = ...
'../data/vehicle/ephem/ccsds/CCSDS_BasicEulerFile.aem'
Create Propagator aProp;
Create OrbitView a3DView
a3DView.Add = {aSat,Earth}
BeginMissionSequence;
Propagate aProp(aSat) {aSat.ElapsedSecs = 3600};
Precessing Spinner Model
The PrecessingSpinner attitude mode configures the attitude of a spacecraft to have steady-state
precession motion with respect to a specified vector defined in the inertial frame. The spin axis must
be provided in the spacecraft body frame.
To configure the spin axis of the spacecraft body, set the BodySpinAxis, which is expressed in the
body frame, and define the reference vector of the steady-state precession motion using the NutationReferenceVector, which is expressed in the inertial frame. To configure the initial attitude
of the spacecraft, set InitialPrecessionAngle to define the initial angle of the precession, set InitialSpinAngle to define the initial angle of the spin, and set NutationAngle to define the nutation
angle which is constant. To configure the rate of precession and spin rate, set PrecessingRate and
SpinRate which are constant.
547
Reference Guide
Spacecraft Attitude
Note
The PrecessingSpinner model uses the cross product of the BodySpinAxis axis and
the inertial x-axis as a reference for the initial attitude. To avoid an undefined attitude
when the spin axis is aligned, or nearly aligned, with the inertial x-axis, a different reference vector is used in that case. In the event that the cross product of BodySpinAxis
and the inertial x-axis is less than 1e-5, the inertial y-axis is used as the reference vector.
For further details see the engineering/mathematical specifications.
The script example below shows how to configure a Spacecraft to have PrecessingSpinner attitude
mode where the body z-axis spins with respect to the inertial z-axis. PrecessionRate is set to 1 deg./
sec., InitialPrecessionAngle is set to 0 deg./sec., SpinRate is set to 2 deg./sec., InitialSpinAngle
is set to 0 deg./sec., and NutationAngle is set to 30 deg.
Create Spacecraft aSat;
GMAT aSat.Attitude = PrecessingSpinner;
GMAT aSat.NutationReferenceVectorX = 0;
GMAT aSat.NutationReferenceVectorY = 0;
GMAT aSat.NutationReferenceVectorZ = 1;
GMAT aSat.BodySpinAxisX = 0;
GMAT aSat.BodySpinAxisY = 0;
GMAT aSat.BodySpinAxisZ = 1;
GMAT aSat.InitialPrecessionAngle = 0;
GMAT aSat.PrecessionRate = 1;
GMAT aSat.NutationAngle = 30;
GMAT aSat.InitialSpinAngle = 0;
GMAT aSat.SpinRate = 2;
548
Spacecraft Attitude
Reference Guide
Create OrbitView OrbitView1;
OrbitView1.Add = {aSat, Earth}
OrbitView1.ViewPointReference = Earth
OrbitView1.ViewPointVector = [ 30000 0 0 ]
Create Propagator aProp
aProp.MaxStep = 10
BeginMissionSequence
Propagate aProp(aSat) {aSat.ElapsedSecs = 12000.0}
549
550
Reference Guide
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. GMAT
supports a spherical SRP model, and higher fidelity SRP file option.
See Also: Propagate, Propagator,Spacecraft
Fields
Field
Description
Cd
The coefficent of drag used to compute the acceleration due to drag.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
Cr
The coefficent of reflectivity used to compute the acceleration due to SRP.
A value of zero means the spacecraft is translucent to incoming radiation.
A value of 1.0 indicates all radiaion is absorbed and all the force is transmitted to the spacecraft. A value of 2.0 indicates all radiation is reflected
and twice the force is transmitted to the spacecraft.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
Drag Area
Real
Real >= 0
set, get
2.2
dimensionless
GUI, script
Real
0 <= Cr <= 2.0
set, get
1.8
dimensionless
GUI, script
The area used to compute acceleration due to atmospheric drag.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
Real
Real > = 0
set, get
15
m^2
GUI, script
551
Reference Guide
Spacecraft Ballistic/Mass Properties
Field
Description
DryMass
The dry mass of the Spacecraft (does not include fuel mass).
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
SPADSRPFile
Name ( and optionally path information) of SPAD file.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
SPADSRPScaleFactor
Real
Real >= 0
set
1
dimensionless
GUI, script
The area used to compute acceleration due to solar radiation pressure.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
552
String
valid path and SPAD file
set
N/A
N/A
GUI, script
Scale factor applied to SRP force when using a SPADModel in the propagation.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
SRPArea
Real
Real >=0
set, get
850
kg
GUI, script
Real
Real > 0
set, get
1
m^2
GUI, script
Spacecraft Ballistic/Mass Properties
Reference Guide
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. GMAT supports
a spherical SRP model and a SPAD (Solar Pressure and Aerodynamic Drag) file.
Remarks
Configuring Ballistic and Mass Properties for the Spherical Model
GMAT supports a cannonball model for drag and SRP modeling. 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.
Configuring Ballistic and Mass Properties for the SRP File
The (SPAD) SRP file can be used for high fidelity SRP modelling taking into account the physical
properties of the spacecraft (shape and reflectivity) and the spacecraft attitude. SPAD stands for
Solar Pressure and Aerodynamic Drag. SPAD files are tabulated data that contain the spacecraft area
scaled by physical properties like Cr including specular, diffuse, and reflective properties. Data is
expressed as a function of azimuth and elevation in the spacecraft body frame. Note: the azimuth
and elevation tabulated on the file are the azimuth and elevation of the vector from the Sun, to the
Spacecraft, expressed in the body frame. To compute the SRP acceleration, GMAT computes the
sun vector’s azimuth and elevation in the spacecraft body frame, and then interpolates the SPAD
data using bi-linear interpolation. Note that this formulation results in an attitude dependent SRP
acceleration. For more details on the computation and configuration of drag and SRP models see
the Force Model documentation.
553
Reference Guide
Spacecraft Ballistic/Mass Properties
Caution
When using a SPAD SRP file, GMAT uses the attitude defined on the Spacecraft resource to compute the Sun's positon in the body frame. If the attitude uses a coordinate
system with Axes set to ObjectReferenced, and those axes refer back to the Spacecraft orbit state (i.e. VNB or LVLH systems), GMAT holds the attitude constant over
a given integration step. In those cases, we recommend carefully choosing a maximum
step size small enough to ensure the resulting approximation is acceptable for your application.
A valid SPAD file header, and the first three lines of data are shown below for illustrative purposes.
Note, GMAT does not use all values provide on the file and GMAT's usage of SPAD files is described
in detail in the table below the example.
Version
System
Analysis Type
Pixel Size
Spacecraft Size
Pressure
Center of Mass
Current time
Motion
Name
Method
Minimum
Maximum
Step
Motion
Name
Method
Minimum
Maximum
Step
: END
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
4.21
sphericalSat
Area
5
436.2
1
(50.9, 184.9, -49)
May 7, 2009 15:53:38.00
Record count
1
Azimuth
Step
-180
180
5
2
Elevation
Step
-90
90
5
: 2701
AzimuthElevatio Force(X) Force(Y) Force(Z)
degrees degrees
m^2
m^2
m^2
------- ------- --------- --------- --------- ---------180.00
-90.00 -0.00000000000000 -0.00000000000000 -8.94500000000000
-180.00
-85.00 -0.77960811887780 -0.00000000000000 -8.91096157443066
-180.00
-80.00 -1.55328294923069 -0.00000000000000 -8.80910535069420
A SPAD file contains three sections as illustrated below. Data specifications for items in each section
are described in the tables below
554
Spacecraft Ballistic/Mass Properties
Reference Guide
A SPAD file header may contain many fields but only a few are used by GMAT as described below.
Other fields are ignored.
Keyword
Re- Description and Supported Values
quired
Analysis Type
Y
The SPAD software can creates files with Analysis Types of Solar
Pressure, Area, and Drag. GMAT only supports the Area option.
Example:
Analysis Type : Area
Pressure
N
SPAD supports the ability to apply a pressure scale factor for SRP
files. GMAT does not read this value, but the SRP properties on
the file have been scaled by the Pressure factor. The value is usually
“1”. However, when not 1, it is possible to apply an SRP scale
factor twice, once from the value applied in SPAD, and once from
SPADSRPScaleFactor. Care should be taken to ensure that if the
desired scale factor was applied during file creation that it is not
reapplied in GMAT.
The SPAD file Motion Data section describes the data contained in the body of the file. The Motion
Data fields used by GMAT are described below. Others are ingored.
Keyword
Re- Description and Supported Values
quired
Motion
Y
Together, the Motion and Name fields specify the type of data in
the first two columns of the body of the file. GMAT currently
supports Azimuth and Elevation Motion only (no articulating appendages) and requires that the first Motion is Azimuth and the
second Motion is Elevation as shown below.
Examples:
Motion : 1
Name : Azimuth
and
Motion : 2
Name : Elevation
555
Reference Guide
Spacecraft Ballistic/Mass Properties
Keyword
Re- Description and Supported Values
quired
Name
Y
Together, the Motion and Name fields specify the type of data in
the first two columns of the body of the file. GMAT currently
supports Azimuth and Elevation Motion only (no articulating appendages) and requires that the first Motion is Azimuth and the
second Motion is Elevation as shown below.
Examples:
Motion : 1
Name : Azimuth
and
Motion : 2
Name : Elevation
Method
Y
The step size in the independent variable. The only supported value is Step.
Example:
Motion : 1
Method : Step
Maximum
Y
The maximum value for an independent variable (Motion Type).
For Azimuth, Maximum must be 180, and for Elevation Maximum
must be 90.
Example:
Motion : 1
Name : Azimuth
Maximum : 180
Motion : 2
Name : Elevation
Maximum : 90
556
Spacecraft Ballistic/Mass Properties
Reference Guide
Keyword
Re- Description and Supported Values
quired
Minimum
Y
The minimum value for an independent variable. (Motion Type).
For Azimuth, minimum must be -180, and for Elevation minimum
must be -90.
Example:
Motion : 1
Name : Azimuth
Minimum : -180
Motion : 2
Name : Elevation
Minimum : -90
Step
Y
The step size for the independent variable (Motion Type). If Step
does not divide evenly into the variable range, then errors may
occur because the maximum and/or minimum values may not be
on the file.
Example:
Motion : 1
Step : 15
Record count
Y
Record count is the number of rows of data in the data segment.
Record count = (360/(Azimuth Step) +1)*(180/(Elevation Step)
+1).
Example:
Record count : 325
The SPAD file data block contains tabulated acceleration data as described below.
557
Reference Guide
Spacecraft Ballistic/Mass Properties
Keyword
Re- Description and Supported Values
quired
Azimuth
Y
Azimuth data column. Must be first column in the data. Units must
be degrees. Azimuth is the azimuth of the vector from spacecraft
to sun, expressed in the body frame: atan2(ySun,xSun)).
Example:
AzimuthElevatio
degrees degrees
------- -------180.00 -90.00
-180.00 -75.00
-180.00 -60.00
Elevation
N
Elevation data column. Must be second column in the data. Units must be degrees. Elevation is the elevation of the
vector from spacecraft to sun, expressed in the body frame:
atan2(zSun,sqrt(xSun^2 + ySun^2)).
Example:
AzimuthElevatio
degrees degrees
------- -------180.00 -90.00
-180.00 -75.00
-180.00 -60.00
Force(*)
N
Area vector columns. Must be columns 3-5 in the data. Quantities
must be in base units of m^2,mm^2,cm^2,in^2,ft^2. If another
unit is provided in the header lines, an exception is thrown. The
area vector is the direction of the resulting SRP force, scaled by
area and Cr properties.
Example: See code listing above.
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
558
Spacecraft Ballistic/Mass Properties
Reference Guide
total mass of a spacecraft to be negative. However, GMAT will allow the mass of a ChemicalTank
to be negative. See the ChemicalTank documentation for details.
Examples
Configure physical properties for a spherical SRP model.
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})
Configure a SPAD SRP model.
Create Spacecraft aSpacecraft;
aSpacecraft.DryMass
= 2000
aSpacecraft.SPADSRPFile = '..\data\vehicle\spad\SphericalModel.spo'
aSpacecraft.SPADSRPScaleFactor = 1;
Create ForceModel aFM;
aFM.SRP = On;
aFM.SRP.SRPModel = SPADFile
Create Propagator aProp;
aProp.FM = aFM;
BeginMissionSequence
Propagate aProp(aSpacecraft) {aSpacecraft.ElapsedDays = 0.2}
559
560
Reference Guide
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 Type
GMAT
common
reference epoch
05 Jan 1941 12:00:00.000
17 Nov 1858 00:00:00.000
Modified Julian offset
2430000.0
2400000.5
Fields
Field
Description
DateFormat
The time system and format of the Epoch field. In the GUI, this
field is called EpochFormat.
Data Type
Allowed Values
Access
Default Value
Interfaces
Enumeration
A1ModJulian, TAIModJulian, UTCModJulian, TTModJulian, TDBModJulian, A1Gregorian, TAIGregorian,
TTGregorian, UTCGregorian, TDBGregorian
set only
TAIModJulian
GUI, script
561
Reference Guide
Spacecraft Epoch
Field
Description
Epoch
The time and date corresponding to the specified orbit state.
Data Type
Allowed Values
Access
Default Value
Interfaces
A1ModJulian
String
See Epoch
set, get (mission sequence only)
21545.00000039794
Days
script
The spacecraft orbit epoch in the A.1 system and the Modified
Julian format.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
CurrA1MJD
Modified Julian: 6116.0 <= Epoch <=
58127.5
set only
21545
GUI, script
The Spacecraft orbit epoch in the A.1 system and the Modified
Julian format.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
Epoch.A1ModJulian
Time
Gregorian: 04
Oct
1957
12:00:00.000 <= Epoch <= 28
Feb 2100 00:00:00.000
String
See Epoch
set, get
21545.00000039794
Days
none
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
Allowed Values
Access
Default Value
Interfaces
562
Time
6116.0 <= CurrA1MJD <= 58127.5
get, set (mission sequence only)
converted equivalent of 21545 Modified
Julian (TAI)
script only
Spacecraft Epoch
Reference Guide
Field
Description
A1Gregorian
The Spacecraft orbit epoch in the A.1 system and the Gregorian
format.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
TAIGregorian
The Spacecraft orbit epoch in the TAI system and the Gregorian
format.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
TAIModJulian
String
See Epoch
set, get (mission sequence only)
21545
See A1ModJulian
GUI, script
The Spacecraft orbit epoch in the TDB system and the Gregorian
format.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
TDBModJulian
String
See Epoch
set, get (mission sequence only)
01 Jan 2000 12:00:00.000
Gregorian date
GUI, script
The Spacecraft orbit epoch in the TAI system and the Modified
Julian format.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
TDBGregorian
String
See Epoch
set, get (mission sequence only)
01 Jan 2000 12:00:00.034
N/A
GUI, script
String
See Epoch
set, get (mission sequence only)
01 Jan 2000 12:00:32.184
See A1Gregorian
GUI, script
The Spacecraft orbit epoch in the TDB system and the Modified
Julian format.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
String
See Epoch
set, get (mission sequence only)
21545.00037249916
See A1ModJulian
GUI, script
563
Reference Guide
Spacecraft Epoch
Field
Description
TTGregorian
The Spacecraft orbit epoch in the TT system and the Gregorian
format.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
TTModJulian
The Spacecraft orbit epoch in the TT system and the Modified
Julian format.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
UTCGregorian
String
See Epoch
set, get (mission sequence only)
21544.99962962963
See A1ModJulian
GUI, script
The Spacecraft orbit epoch in the A.1 system and the Gregorian
format.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
564
String
See Epoch
set, get (mission sequence only)
01 Jan 2000 11:59:28.000
See A1Gregorian
GUI, script
The Spacecraft orbit epoch in the UTC system and the Modified
Julian format.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
Epoch.A1Gregorian
String
See Epoch
set, get (mission sequence only)
21545.0003725
See A1ModJulian
GUI, script
The Spacecraft orbit epoch in the UTC system and the Gregorian
format.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
UTCModJulian
String
See Epoch
set, get (mission sequence only)
01 Jan 2000 12:00:32.184
See A1Gregorian
GUI, script
String
See Epoch
set, get
01 Jan 2000 12:00:00.034
N/A
GUI, script
Spacecraft Epoch
Reference Guide
Field
Description
Epoch.TAIGregorian
The Spacecraft orbit epoch in the TAI system and the Gregorian
format.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
Epoch.TAIModJulian
The Spacecraft orbit epoch in the TAI system and the Modified
Julian format.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
Epoch.TDBGregorian
String
See Epoch
set, get
01 Jan 2000 12:00:32.184
See Epoch.A1Gregorian
GUI, script
The Spacecraftorbit epoch in the TDB system and the Modified
Julian format.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
Epoch.TTGregorian
String
See Epoch.A1ModJulian
set, get
21545
See Epoch.A1ModJulian
GUI, script
The Spacecraft orbit epoch in the TDB system and the Gregorian
format.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
Epoch.TDBModJulian
String
See Epoch
set, get
DefaultValue
01 Jan 2000 12:00:00.000
GUI, script
String
See Epoch
set, get
21545.00037249916
See Epoch.A1ModJulian
GUI, script
The Spacecraft orbit epoch in the TT system and the Gregorian
format.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
String
See Epoch
set, get
01 Jan 2000 12:00:32.184
See Epoch.A1Gregorian
GUI, script
565
Reference Guide
Spacecraft Epoch
Field
Description
Epoch.TTModJulian
The Spacecraftorbit epoch in the TT system and the Modified
Julian format.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
Epoch.UTCGregorian
The Spacecraftorbit epoch in the UTC system and the Gregorian
format.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
Epoch.UTCModJulian
String
See Epoch
set, get
01 Jan 2000 11:59:28.000
See Epoch.A1Gregorian
GUI, script
The Spacecraft orbit epoch in the UTC system and the Modified
Julian format.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
566
String
See Epoch
set, get
21545.0003725
See Epoch.A1ModJulian
GUI, script
String
Range
See Epoch
21544.99962962963
See Epoch.A1ModJulian
GUI, script
Spacecraft Epoch
Reference Guide
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.1
USNO atomic time; GMAT’s internal time system
TAI
International Atomic Time
TDB
Barycentric Dynamical Time
TT
Terrestrial Time
UTC
Coordinated Universal Time
567
Reference Guide
Gregorian
Spacecraft Epoch
Text with the following format: dd mmm yyyy
HH:MM:SS.FFF
dd
mmm
yyyy
HH
MM
SS
FFF
Modified Julian
two-digit day of month
first three letters of month
four-digit year
two-digit hour
two-digit minute
two-digit second
three-digit fraction of second
Floating-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”. From the International Astronomical Union's Standards of Fundamental Astronomy "SOFA Time Scale and Calendar Tools"
documentation: "Note that UTC has to be expressed as hours, minutes and seconds (or at least in seconds in a
given day) if leap seconds are to be taken into account in the correct manner. In particular, it is inappropriate to
express UTC as a Julian Date, because there will be an ambiguity during a leap second so that for ex568
Spacecraft Epoch
Reference Guide
ample 1994 June 30 23:59:60:0 and 1994 July 1 00:00:00:0 would both come out as MJD 49534.00000
and because subtracting two such JDs would not yield the correct interval in cases that contain leap
seconds." For this reason, we discourage use of the UTC modified Julian system, and recommend
using UTC Gregorian when a UTC time system is required.
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
569
Reference Guide
aPlot.XVariable = aSat.Epoch.TTModJulian
aPlot.YVariables = aSat.Earth.RMAG
Create Report aReport
aReport.Add = {aSat.Epoch.A1Gregorian, aSat.Earth.RMAG}
570
Spacecraft Epoch
Reference Guide
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 ChemicalTank, ChemicalThruster ,ElectricTank, and ElectricThruster. Before
you attach a hardware model to a Spacecraft, you must first create the model.
See Also: ChemicalTank, ChemicalThruster,ElectricTank, ElectricThruster
Fields
Field
Description
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
Allowed Values
Access
Default Value
Units
Interfaces
Thrusters
Reference Array
A list of ChemicalTanks and Chemical Thrusters.
set
N/A
N/A
GUI, script.
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
Allowed Values
Access
Default Value
Units
Interfaces
Reference Array
A list of ChemicalThrusters and ElectricThrusters.
set
N/A
N/A
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. Note the discussion below uses a chemical system as an example but applies equally
to electric systems.
As shown below, to add a ChemicalTank to your script, highlight the Hardware resource and then
right click to add a ChemicalTank.
571
Reference Guide
Spacecraft Hardware
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 ChemicalTank and a ChemicalThruster. Next, we attach both
the ChemicalTank and the ChemicalThruster 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.
572
Spacecraft Hardware
Reference Guide
Next, select the desired ChemicalTank and use the right arrow button to attach the ChemicalTank
to the Spacecraft as shown below. Then click the Apply button.
Similarly, to attach a ChemicalThruster to a Spacecraft, double click on the desired Spacecraft
under the Spacecraft resource and then select the Actuators tab. Then select the desired ChemicalThruster and use the right arrow to attach the ChemicalThruster to the Spacecraft as shown
below. Finally, click the Apply button.
573
Reference Guide
Spacecraft Hardware
Remarks
To use a Thruster to apply a finite burn to a Spacecraft, additional steps are required. For example,
when you create the ChemicalThruster resource, you have to associate a ChemicalTank with the
ChemicalThruster. For details on this and related matters, see the help for the ChemicalTank,
ChemicalThruster, and FiniteBurn resources.
Examples
Create a default Spacecraft. Create ChemicalTank and ChemicalThruster resources and attach
them to the Spacecraft.
% Create default Spacecraft, ChemicalTank, and Thruster Resources
Create Spacecraft DefaultSC
Create ChemicalTank FuelTank1
Create ChemicalThruster Thruster1
% Attach ChemicalTank and Thruster to the spacecraft
DefaultSC.Thrusters = {Thruster1}
DefaultSC.Tanks = {FuelTank1}
BeginMissionSequence
574
Reference Guide
Spacecraft Navigation
There are a number of Spacecraft fields that are used exclusively to support GMAT's navigation
capability.
Description
When using GMAT's navigation capabilities, certain Spacecraft parameters can be "solved-for." As
discussed in the Spacecraft Ballistic/Mass Properties section, the Spacecraft ballistic and mass properties include the coefficient of reflectivity, Cr, and the coefficient of drag, Cd. As discussed in
the Spacecraft Orbit State section, you can specify the CartesianState, i.e., the X, Y, Z position
(km), and the Vx, Vy, Vz velocity (km/s) of a Spacecraft. As part of GMAT's navigation capability,
GMAT can ingest measurements and estimate ("solve-for") values for Cr, Cd, and CartesianState.
See Also: BatchEstimatorInv
Fields
Field
Description
AddHardware
List of Antenna, Transmitter, Receiver, and Transponder objects attached to a Spacecraft
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
CdSigma
Antenna, Transmitter, Receiver, or Transponder object
Any user defined Antenna, Transmitter, Receiver, or Transponder object
set
None
N/A
script
Standard deviation of the coefficient of reflectivity, Cd. This field is only used if the UseInitialCovariance field of the BatchEstimatorInv resource is set to True and Cd is being solved for.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
Real
Real > 0
set
1e70
dimensionless
script
575
Reference Guide
Spacecraft Navigation
Field
Description
CrSigma
Standard deviation of the coefficient of reflectivity, Cr. This field is only used if the UseInitialCovariance field of the BatchEstimatorInv resource is set to True and Cr is being solved for.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
Real
Real > 0
set
1e70
dimensionless
script
EstimationStateType Choice of 6-element state type to be solved for. Currently, Cartesian is
the only allowed value. This field only has a function if the CartesianState
is being solved-for.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
OrbitErrorCovariance
Cartesian State 6x6 error covariance matrix. This field is only used if
the UseInitialCovariance of the BatchEstimatorInv resource is set to
True and the CartesianState is being solved for.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
SolveFors
Real Matrix
6x6 positive definite symmetric Array
set
6x6 diagonal matrix with 1e70 in all diagonal entries.
Covariance matrix where position specified in km
and velocity in km/s. (Thus, first three diagonal
elements have units km^2 and last three diagonal
elements have units (km/s)^2)
script
List of fields to be solved for. Currently, if anything is solved for, then
CartesianState must be included as a solve-for. For example, Cr cannot
be the only parameter solved for.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
576
Enumeration
Cartesian
set
Cartesian
N/A
script
StringArray
CartesianState, Cr, Cd
set
None
N/A
script
Spacecraft Navigation
Reference Guide
Examples
Solve for Cr and the spacecraft Cartesian state.
Create Spacecraft Sat
Create BatchEstimatorInv bat
Sat.SolveFors = {CartesianState, Cr}
%User must create a TrackingFileSet
%and set up bat appropriately
BeginMissionSequence
RunEstimator bat
Solve for Cd and the spacecraft Cartesian state assuming that the a priori information is included in
the estimation state vector.
Create Spacecraft Sat
Sat.SolveFors = {CartesianState, Cd}
Create BatchEstimatorInv bat
bat.UseInitialCovariance= True
%User must create a TrackingFileSet
%and set up bat appropriately
Create Array Initial_6x6_covariance[6,6]
BeginMissionSequence
Initial_6x6_covariance = ...
diag([1e-6 1e70 1e70 1e70 1e70 1e70]) %X pos known very well
Sat.OrbitErrorCovariance = Initial_6x6_covariance
Sat.CrSigma = 1e-6
%Cr known very well
RunEstimator bat
577
578
Reference Guide
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
Field
Description
AltEquinoctialP
A measure of the orientation of the orbit. AltEquinoctialP and AltEquinoctialQ together govern how an orbit is oriented. AltEquinotialP =
sin(INC/2)*sin(RAAN).
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
AltEquinoctialQ
Real
-1 ≤ AltEquinoctialP ≤ 1
set, get
0.08982062789020774
(None)
GUI, script
A measure of the orientation of the orbit. AltEquinoctialP and AltEquinoctialQ together govern how an orbit is oriented. AltEquinotialP =
sin(INC/2)*cos(RAAN).
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
Real
-1 ≤ AltEquinoctialQ ≤ 1
set, get
0.06674269576352432
(None)
GUI, script
579
Reference Guide
Spacecraft Orbit State
Field
Description
AOP
The orbital argument of periapsis expressed in the coordinate system chosen in the CoordinateSystem field.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
AZI
The orbital velocity azimuth expressed in the coordinate system chosen in
the CoordinateSystem field.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
BrouwerLongAOP
BrouwerShortAOP
BrouwerShortECC
Data Type
Allowed Values
Real
-∞ < BrouwerLongAOP/BrouwerShortAOP
<∞
set, get
Conversion from default Cartesian state
deg
GUI, script
Brouwer-Lyddane long-term averaged (short-term averaged) mean eccentricity.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
580
Real
-∞ < AZI < ∞
set, get
82.37742168155043
deg.
GUI, script
Brouwer-Lyddane long-term averaged (short-term averaged) mean argument of periapsis.
Access
Default Value
Units
Interfaces
BrouwerLongECC
Real
-∞ < AOP < ∞
set, get
314.1905515359921
deg.
GUI, script
Real
0 ≤ BrouwerLongECC/BrouwerShortECC ≤
0.99
set, get
Conversion from default Cartesian state
N/A
GUI, script
Spacecraft Orbit State
Reference Guide
Field
Description
BrouwerLongINC
Brouwer-Lyddane long-term averaged (short-term averaged) mean inclination.
BrouwerShortINC
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
BrouwerLongMA
BrouwerShortMA
Real
0 ≤ BrouwerLongINC/BrouwerShortINC ≤
180
set, get
Conversion from default Cartesian state
deg
GUI, script
Brouwer-Lyddane long-term averaged (short-term averaged) mean MA
(mean anomaly).
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
Real
-∞ < BrouwerLongMA/BrouwerShortMA <
∞
set, get
Conversion from default Cartesian state
deg
GUI, script
BrouwerLongRAAN Brouwer-Lyddane long-term averaged (short-term averaged) mean RAAN
(right ascension of the ascending node).
BrouwerShortRAAN
Data Type
Real
Allowed Values
-∞ < BrouwerLongRAAN/BrouwerShortRAAN < ∞
Access
set, get
Default Value
Conversion from default Cartesian state
Units
deg
Interfaces
GUI, script
BrouwerLongSMA
Long-term averaged (short-term averaged) mean semi-major axis.
BrouwerShortSMA
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
Real
Brouwer*SMA > 3000/(1-Brouwer*ECC)
set, get
Conversion from default Cartesian state
km
GUI, script
581
Reference Guide
Spacecraft Orbit State
Field
Description
CoordinateSystem
The coordinate system with respect to which the orbital state is defined.
The CoordinateSystem field is dependent upon the DisplayStateType
field. If the coordinate system chosen by the user does not have a gravitational body at the origin, then the state types Keplerian, ModifiedKeplerian, and Equinoctial are not permitted.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
DEC
The declination of the orbital position expressed in the coordinate system
chosen in the CoordinateSystem field.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
DECV
Real
-90 ≤ DECV ≤ 90
set, get
7.747772036108118
deg
GUI, script
Delaunay "g" element, identical to AOP, expressed in the coordinate system chosen in the CoordinateSystem field.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
582
Real
-90 ≤ DEC ≤ 90
set, get
10.37584492005105
deg
GUI, script
The declination of orbital velocity expressed in the coordinate system chosen in the CoordinateSystem field.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
Delaunayg
String
CoordinateSystem resource
set
EarthMJ2000Eq
N/A
GUI, script
Real
-∞ < Delaunayg < ∞
set, get
314.1905515359921
deg
GUI, script
Spacecraft Orbit State
Reference Guide
Field
Description
DelaunayG
Delaunay "G" element, the magnitude of the orbital angular momentum,
expressed in the coordinate system chosen in the CoordinateSystem
field.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
Delaunayh
Delaunay "h" element, identical to RAAN, expressed in the coordinate
system chosen in the CoordinateSystem field.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
DelaunayH
Real
-∞ < Delaunayh < ∞
set, get
306.6148021947984
deg
GUI, script
Delaunay "H" element, the z-component of the orbital angular momentum
vector, expressed in the coordinate system chosen in the CoordinateSystem field.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
Delaunayl
Real
0 ≤ DelaunayG < ∞
set, get
53525.52895581695
km2/s
GUI, script
Real
-∞ < Delaunayl < ∞
set, get
52184.99999999999
km2/s
GUI, script
Delaunay "ℓ" element, identical to the mean anomaly, expressed in the
coordinate system chosen in the CoordinateSystem field.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
Real
-∞ < Delaunayl < ∞
set, get
97.10782663991999
deg
GUI, script
583
Reference Guide
Spacecraft Orbit State
Field
Description
DelaunayL
Delaunay "L" element, related to the two-body orbital energy, expressed
in the coordinate system chosen in the CoordinateSystem field.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
DisplayStateType
The orbital state type displayed in the GUI. Allowed state types are dependent upon the selection of CoordinateSystem. For example, if the
coordinate system does not have a celestial body at the origin, Keplerian,
ModifiedKeplerian, and Equinoctial are not allowed options for DisplayStateType.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
ECC
Access
Default Value
Units
Interfaces
Real
ECC < 0.9999999 or ECC > 1.0000001. If ECC
> 1, SMA must be < 0
set, get
0.02454974900598137
N/A
GUI, script
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 +
RAAN) .
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
584
String
Cartesian, Keplerian, ModifiedKeplerian,
SphericalAZFPA,
SphericalRADEC,
or
Equinoctial
set
Cartesian
N/A
GUI, script
The orbital eccentricity expressed in the coordinate system chosen in the
CoordinateSystem field.
Data Type
Allowed Values
EquinoctialH
Real
0 ≤ DelaunayL < ∞
set, get
53541.66590560955
km2/s
GUI, script
Real
-0.99999 < EquinoctialH < 0.99999, AND
sqrt(EquinoctialH^2 + EquinoctialK^2) <
0.99999
set, get
-0.02423431419337062
dimless
GUI, script
Spacecraft Orbit State
Reference Guide
Field
Description
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 +
RAAN) .
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
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
Allowed Values
Access
Default Value
Units
Interfaces
EquinoctialQ
Real
-∞ < EquinoctialP < ∞
set, get
-0.09038834725719359
dimless
GUI, script
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
Allowed Values
Access
Default Value
Units
Interfaces
FPA
Real
-0.99999 < EquinoctialK < 0.99999, AND
sqrt(EquinoctialH^2 + EquinoctialK^2) <
0.99999
set, get
-0.003922778585859663
dimless
GUI, script
Real
-∞ < EquinoctialQ < ∞
set, get
0.06716454898232072
dimless
GUI, script
The orbital flight path angle expressed in the coordinate system chosen in
the CoordinateSystem field.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
Real
0 ≤ FPA ≤ 180
set, get
88.60870365370448
Deg.
GUI, script
585
Reference Guide
Spacecraft Orbit State
Field
Description
Id
The spacecraft Id used in tracking data files. This field is only used for
EstimationPlugin protype functionality.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
INC
The orbital inclination expressed in the coordinate system chosen in the
CoordinateSystem field.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
IncomingBVAZI
OutgoingBVAZI
OutgoingC3Energy
Real
-∞ < IncomingBVAZI/OutgoingBVAZI < ∞
set, get
Conversion from default Cartesian state
deg
GUI, script
C3 energy. C3Energy = -mu/SMA. IncomingC3Energy/
OutgoingC3Energy differ only in that they are associated with the IncomingAsymptote and OutgoingAsymptote state representations, respectively.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
586
Real
0 ≤ INC ≤ 180
set, get
12.85008005658097
deg
GUI, script
IncomingBVAZI/OutgoingBVAZI is the B-vector azimuth at infinity
of the incoming/outgoing asymptote measured counter-clockwise from
south. If C3Energy < 0 the apsides vector is substituted for the outgoing/incoming asymptote.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
IncomingC3Energy
String
String
set
SatId
N/A
script
Real
IncomingC3Energy
≤
IncomingC3Energy ≥ 1e-7
-1e-7
or
OutgoingC3Energy
≤
-1e-7
OutgoingC3Energy ≥ 1e-7
set, get
Conversion from default Cartesian state
km2/s2
GUI, script
or
Spacecraft Orbit State
Reference Guide
Field
Description
IncomingDHA
IncomingDHA/OutgoingDHA is the declination of the incoming/outgoing asymptote. If C3Energy < 0 the apsides vector is substituted for
the incoming/outgoing asymptote..
OutgoingDHA
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
IncomingRadPer
OutgoingRadPer
IncomingRHA
OutgoingRHA
The orbital radius of periapsis. The radius of periapsis is the minimum
distance (osculating) between the spacecraft and celestial body at the origin
of coordinate system. IncomingRadPer/OutgoingRadPer differ from
RadPer only in that they are associated with the IncomingAsymptote
and OutgoingAsymptote state representations, respectively.
Data Type
Allowed Values
Real
abs(IncomingRadPer) ≥ 1 meter.
Access
Default Value
Units
Interfaces
abs(OutgoingRadPer) ≥ 1 meter.
set, get
Conversion from default Cartesian state
km
GUI, script
IncomingRHA/OutgoingRHA is the right ascension of the incoming/outgoing asymptote. If C3Energy < 0 the apsides vector is substituted for the incoming/outgoing asymptote.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
MLONG
Real
-90° ≤ IncomingDHA/OutgoingDHA < 90°
set, get
Conversion from default Cartesian state
deg
GUI, script
Real
-∞ < IncomingRHA/OutgoingRHA < ∞
set, get
Conversion from default Cartesian state
deg
GUI, script
A measure of the location of the spacecraft in it's orbit. MLONG = AOP
+ RAAN + MA.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
Real
-360 ≤ MLONG ≤ 360
set, get
357.9131803707105
deg.
GUI, script
587
Reference Guide
Spacecraft Orbit State
Field
Description
ModEquinoctialF
Components of the eccentricity vector (with ModEquinoctialG). The
eccentricity vector has a magnitude equal to the eccentricity and it
points from the central body to perigee. ModEquinoctialF = ECC *
cos(AOP+RAAN)
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
ModEquinoctialG
Components of eccentricity vector (with ModEquinoctialF). ModEquinoctialG = ECC * sin(AOP+RAAN)
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
ModEquinoctialH
Real
-∞ < ModEquinoctialK < ∞
set, get
-0.09038834725719359
(None)
GUI, script
The spacecraft Id used in SPICE kernels.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
588
Real
-∞ < ModEquinoctialH < ∞
set, get
0.06716454898232072
(None)
GUI, script
Idential to EquinoctialP.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
NAIFId
Real
-∞ < ModEquinoctialG < ∞
set, get
-0.02423431419337062
(None)
GUI, script
Identical to EquinoctialQ.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
ModEquinoctialK
Real
-∞ < ModEquinoctialF < ∞
set, get
-0.003922778585859663
(None)
GUI, script
String
String
set
-123456789
N/A
GUI, script
Spacecraft Orbit State
Reference Guide
Field
Description
OrbitSpiceKernelName
SPK Kernels for spacecraft orbit. SPK orbit kernels have extension
".BSP". This field cannot be set in the Mission Sequence.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
PlanetodeticAZI
The orbital velocity azimuth expressed in the coordinate system chosen in
the CoordinateSystem field. Unlike the AZI field, PlanetodeticAZI is
associated with the Planetodetic state representation, which is only valid
for coordinate systems with BodyFixed axes.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
PlanetodeticHFPA
Real
-∞ < PlanetodeticAZI < ∞
set, get
81.80908019114962
deg
GUI, script
The orbital horizontal flight path angle expressed in the coordinate system
chosen in the CoordinateSystem field. PlanetodeticHFPA is only valid
for coordinate systems with BodyFixed axes.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
PlanetodeticLAT
String array
List of path and filenames.
set
No Default. The field is empty.
N/A
GUI, script
Real
-90 ≤ PlanetodeticHFPA ≤ 90
set, get
1.494615814842774
deg
GUI, script
The planetodetic latitude expressed in the coordinate system chosen in the
CoordinateSystem field. This field is only valid for coordinate systems
with BodyFixed axes.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
Real
-90 ≤ PlanetodeticLAT ≤ 90
set, get
10.43478253114861
deg
GUI, script
589
Reference Guide
Spacecraft Orbit State
Field
Description
PlanetodeticLON
The planetodetic longitude expressed in the coordinate system chosen in
the CoordinateSystem field. This field is only valid for coordinate systems with BodyFixed axes.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
PlanetodeticRMAG
The magnitude of the orbital position vector expressed in the coordinate
system chosen in the CoordinateSystem field. Unlike the RMAG field,
PlanetodeticRMAG is associated with the Planetodetic state representation, which is only valid for coordinate systems with BodyFixed axes.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
PlanetodeticVMAG
Real
PlanetodeticVMAG ≥ 1e-10
set, get
6.905049647173787
km/s
GUI, script
The right ascension of the orbital position expressed in the coordinate
system chosen in the CoordinateSystem field.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
590
Real
PlanetodeticRMAG ≥ 1e-10
set, get
7218.032973047435
km
GUI, script
The magnitude of the orbital velocity vector expressed in the coordinate
system chosen in the CoordinateSystem field. Unlike the VMAG field,
PlanetodeticVMAG is associated with the Planetodetic state representation, which is only valid for coordinate systems with BodyFixed axes.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
RA
Real
-∞ < PlanetodeticLON < ∞
set, get
79.67188405807977
deg
GUI, script
Real
-∞ < RA < ∞
set,get
0
deg
GUI, script
Spacecraft Orbit State
Reference Guide
Field
Description
RAAN
The orbital right ascension of the ascending node expressed in the coordinate system chosen in the CoordinateSystem field.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
RadApo
The orbital radius of apoapsis expressed in the coordinate system chosen
in the CoordinateSystem field. The radius of apoapsis is the maximum
distance (osculating) between the Spacecraft and celestial body at the origin of CoordinateSystem.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
RadPer
Real
abs(RadApo) ≥ 1 meter.
set, get
7368.49911046818
km
GUI, script
The orbital radius of periapsis expressed in the coordinate system chosen
in the CoordinateSystem field. The radius of periapsis is the minimum
distance (osculating) between the Spacecraft and celestial body at the origin of CoordinateSystem.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
RAV
Real
-∞ < RAAN < ∞
set, get
306.6148021947984
deg
GUI, script
Real
abs(RadPer) ≥ 1 meter.
set, get
7015.378524789846
km
GUI, script
The right ascension of orbital velocity expressed in the coordinate system
chosen in the CoordinateSystem field.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
Real
-∞ < RAV < ∞
set,get
90
deg
GUI, script
591
Reference Guide
Spacecraft Orbit State
Field
Description
RMAG
The magnitude of the orbital position vector expressed in the coordinate
system chosen in the CoordinateSystem field.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
SemilatusRectum
Magnitude of the position vector when at true anomaly of 90 deg.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
SMA
Access
Default Value
Units
Interfaces
Real
-∞ < TA < ∞
set, get
99.8877493320488
deg.
GUI, script
True longitude of the osculating orbit. TLONG = RAAN + AOP + TA
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
592
Real
SMA < -0.001 m or SMA > 0.001 meter. If SMA
< 0, then ECC must be > 1
set, get
7191.938817629013
km
GUI, script
The orbital true anomaly expressed in the coordinate system chosen in the
CoordinateSystem field.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
TLONG
Real
SemilatusRectum > 1e-7
set, get
7187.60430675539
km
GUI, script
The orbital semi-major axis expressed in the coordinate system chosen in
the CoordinateSystem field.
Data Type
Allowed Values
TA
Real
RMAG ≥ 1e-10
set, get
7218.032973047435
km
GUI, script
Real
-∞ < TLONG < ∞
set, get
0.6931030628392251
deg
GUI, script
Spacecraft Orbit State
Reference Guide
Field
Description
VMAG
The magnitude of the orbital velocity vector expressed in the coordinate
system chosen in the CoordinateSystem field.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
VX
The x-component of the Spacecraft velocity with respect to the coordinate system chosen in the spacecraft's CoordinateSystem field.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
VY
Real
-∞ < VY < ∞
set, get
7.35
km/s
GUI, script
The z-component of the Spacecraft velocity with respect to the coordinate system chosen in the spacecraft's CoordinateSystem field.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
X
Real
-∞ < VX < ∞
set, get
0
km/s
GUI, script
The y-component of the Spacecraft velocity with respect to the coordinate system chosen in the spacecraft's CoordinateSystem field.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
VZ
Real
VMAG ≥ 1e-10
set, get
7.417715281675348
km/s
GUI, script
Real
-∞ < VZ < ∞
set, get
1
km/s
GUI, script
The x-component of the Spacecraft position with respect to the coordinate system chosen in the spacecraft's CoordinateSystem field.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
Real
-∞ < X < ∞
set,get
7100
km
GUI, script
593
Reference Guide
Spacecraft Orbit State
Field
Description
Y
The y-component of the Spacecraft position with respect to the coordinate system chosen in the spacecraft's CoordinateSystem field.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
Z
The z-component of the Spacecraft position with respect to the coordinate system chosen in the spacecraft's CoordinateSystem field.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
GUI
594
Real
-∞ < Y < ∞
set, get
0
km
GUI, script
Real
-∞ < Z < ∞
set, get
1300
km
GUI, script
Spacecraft Orbit State
Reference Guide
The Spacecraft orbit state dialog box allows you to set the epoch, coordinate system, and state type
values for the Spacecraft orbital state. When you specify an orbital state, you define the state in
the representation selected in the StateType menu, with respect to the coordinate system specified
in the CoordinateSystem menu, at the epoch defined in the Epoch menu. If the selected CoordinateSystem is time varying, the epoch of the coordinate system is defined by the Epoch field, and
changing the epoch changes the inertial representation of the orbital state.
A change in Epoch Format causes an immediate update to Epoch to reflect the chosen time system
and format.
The Keplerian, ModifiedKeplerian, and Equinoctial state types cannot be computed if the CoordinateSystem does not have a central body at the origin, or if the CoordinateSystem references
the current spacecraft (resulting in a circular reference). For example, if you have selected the Keplerian state type, coordinate systems for which the Keplerian elements cannot be computed do not
appear in the CoordinateSystem menu. Similarly, if you have selected a CoordinateSystem that
does not have a celestial body at the origin, Keplerian-based state types will not appear as options in
the StateType menu. The Planetodetic state type cannot be selected untill the CoordinateSystem
has BodyFixed axes.
Remarks
Cartesian State
The Cartesian state is composed of the position and velocity components expressed with respect
to the selected CoordinateSystem.
Keplerian and Modified Keplerian State Types
The Keplerian and ModifiedKeplerian state types use the osculating Keplerian orbital elements
with respect to the selected CoordinateSystem. To use either the Keplerian or ModifiedKeplerian
state type, the Spacecraft’s coordinate system must have a central body at the origin. The two representations differ in how the orbit size and shape are defined. The Keplerian state type is composed
of the following elements: SMA, ECC, INC, RAAN, AOP, and TA. The ModifiedKeplerian state
type is composed of the following elements: RadApo, RadPer, INC, RAAN, AOP, and TA. The
tables and figures below describe each Keplerian state element in detail including singularities.
Geometry of the Keplerian Elements
Name
Description
SMA
SMA contains information on the type and size of an orbit. If SMA > 0 the orbit is
elliptic. If SMA <0 the orbit is hyperbolic. SMA is infinite for parabolic orbits.
ECC
ECC contains information on the shape of an orbit. If ECC = 0, then the orbit is
circular. If 0 < ECC < 1, the orbit is elliptical. If , ECC = 1 the orbit is parabolic.
If ECC > 1 then the orbit is hyperbolic.
INC
INC is the angle between the orbit angular momentum vector and the z-axis. If INC
< 90 deg., then the orbit is prograde. If INC > 90 deg, then the orbit is retrograde
RAAN
RAAN is defined as the angle between x-axis and the node vector measured counterclockwise. The node vector is defined as the cross product of the z-axis and orbit
angular momentum vector. RAAN is undefined for equatorial orbits.
595
Reference Guide
Spacecraft Orbit State
Name
Description
AOP
AOP is the angle between a vector pointing at periapsis and a vector pointing in the
direction of the line of nodes. AOP is undefined for circular orbits.
TA
TA is defined as the angle between a vector pointing at periapsis and a vector pointing
at the spacecraft. TA is undefined for circular orbits.
The Keplerian and ModifiedKeplerian state types have several singularities. The table below describes the different singularities and how each is handled in the state conversion algorithms.
596
Singularity
Comments and Behavior
ECC = 1
SMA is infinite and cannot be used to define the size of the orbit. GMAT
requires ECC < 0.9999999 or ECC > 1.0000001 when setting ECC or
when performing conversions. For transformations performed near these
limits, loss of precision may occur.
ECC = 0
AOP is undefined. If ECC <= 1e-11, GMAT sets AOP to zero in the
conversion from Cartesian to Keplerian/ModKeplerian and includes
all orbital-plane angular displacement in the true anomaly.
SMA = 0
Results in a singular conic section. GMAT requires |SMA| > 1 meter
when inputting SMA.
Spacecraft Orbit State
Reference Guide
Singularity
Comments and Behavior
SMA = INF
SMA is infinite and another parameter is required to capture the size of
the orbit. Keplerian elements are not supported.
INC = 0
RAAN is undefined. If INC < 6e-10, GMAT sets RAAN to 0 in the
conversion from Cartesian to Keplerian/ModKeplerian. Then, if ECC
< 1e-11, AOP is set to 0 and GMAT includes all angular displacement
between the x-axis and the spacecraft in the true anomaly. If ECC ≥ 1e-11,
then AOP is computed as the angle between the eccentricity vector and
the x-axis.
INC = 180
RAAN is undefined. If INC > (180 - 6e-10), GMAT sets RAAN to 0 in
the conversion from Cartesian to Keplerian/ModKeplerian. Then, if
ECC < 1e-11, AOP is set to 0 and GMAT includes all angular displacement between the x-axis and the spacecraft in the true anomaly. If ECC ≥
1e-11, then AOP is computed as the angle between the eccentricity vector
and the x-axis.
RadPer = 0
Singular conic section. GMAT requires RadPer > 1 meter in state conversions.
RadApo = 0
Singular conic section. GMAT requires abs(RadApo) > 1 meter in state
conversions.
Delaunay State Type
The conversion between Delaunay and Cartesian is performed passing through classical Keplerian
state. Therefore, Delaunay state cannot represent parabolic orbits. Also, the Delaunay state cannot
represent hyperbolic orbits because of the definition of DelaunayL, which is not a real value when
SMA is negative. The table below describes the elements of the Delaunay state.
Element
Description
Delaunayl
The mean anomaly. It is related to uniform angular motion on a
circle of radius SMA.
Delaunayg
See “Keplerian State” section, AOP
Delaunayh
See “Keplerian State” section, RAAN
DelaunayL
Related to the two-body orbital energy. DelaunayL =
sqrt(mu*SMA)
DelaunayG
Magnitude of the orbital angular momentum vector. DelaunayG
= DelaunayL*sqrt(1-ECC^2)
DelaunayH
The K component of the orbital angular momentum. DelaunayH
= DelaunayG * cos(INC)
Singularities in the Delaunay Elements
Singularities in the Delaunay elements is the same as the Keplerian elements, because it uses the
Keplerian elements during conversion. See “Keplerian State” section. The table below shows the
additional singularities regarding the Delaunay state type.
597
Reference Guide
Spacecraft Orbit State
Element
Description
ECC > 1
DelaunayL is not real for hyperbolic orbits by its definition.
Brouwer-Lyddane Mean State Type
The BrouwerMeanShort state represents short-term averaged mean motion under low-order zonal
harmonics (i.e. J2-J5). Likewise, BrouwerMeanLong state represents long-term averaged mean motion under low-order zonal harmonics (i.e. J2-J5). GMAT uses JGM-2 zonal coefficients in Brouwer
Mean states algorithms. Both are singular for near parabolic or hyperbolic orbits. To use BrouwerMeanShort/BrouwerMeanLong state type in GMAT, the central body must be the Earth. If the
central body is the Earth, GMAT can calculate BrouwerMeanShort/BrouwerMeanLong state
from the osculating state (Cartesian, Keplerian, etc.) and vice-versa.
Element
Description
BrouwerLongAOP
Brouwer-Lyddane long-term averaged (short-term averaged)
mean argument of periapsis.
BrouwerShortAOP
BrouwerLongMA
Brouwer-Lyddane long-term averaged (short-term averaged)
mean MA (mean anomaly).
BrouwerShortMA
BrouwerLongECC
Brouwer-Lyddane long-term averaged (short-term averaged)
mean eccentricity.
BrouwerShortECC
BrouwerLongINC
Brouwer-Lyddane long-term averaged (short-term averaged)
mean inclination.
BrouwerShortINC
BrouwerLongRAAN
BrouwerShortRAAN
BrouwerLongSMA
Brouwer-Lyddane long-term averaged (short-term averaged)
mean RAAN (right ascension of the ascending node).
Long-term averaged (short-term averaged) mean semi-major axis.
BrouwerShortSMA
Singularities in the Brouwer-Lyddane Mean Elements
The table below shows the characteristics of singularities regarding BrouwerMeanShort/BrouwerMeanLong state and the implemented method to handle the singularities in GMAT state conversion algorithms. Note that because Brouwer-Lyddane mean elements involve an iterative solution,
loss of precision may occur near singularities.
Element
BrouwerSMA <
BrouwerECC)
598
Description
3000/(1- Because Brouwer’s formulation based on Earth’s zonal harmonics,
BrouwerMeanShort and BrouwerMeanLong cannot address
orbits with mean perigee distance is smaller than Earth’s radius,
3000 km because of numerical instability.
Spacecraft Orbit State
Reference Guide
Element
Description
BrouwerLongINC=
63, If given BrouwerLongINC (long-term averaged INC only) is
BrouwerLongINC = 117
close to ic= 63 deg. or 117 deg., the algorithm is unstable because
of singular terms (non-zero imaginary components). Thus, GMAT
cannot calculate osculating elements.
BrouwerLongECC =
BrouwerLongECC ≥ 1
0, If BrouwerECC is larger than 0.9, or BrouwerECC is smaller
than 1E-7, it has been reported that Cartesian to BrouwerMeanLong state does not converge statistically. For these cases, GMAT
gives a warning message with the current conversion error.
Spherical State Types
The SphericalAZFPA and SphericalRADEC state types are composed of the polar coordinates
of the spacecraft state expressed with respect to the selected CoordinateSystem. The two spherical
representations differ in how the velocity is defined. The SphericalRADEC state type is composed
of the following elements: RMAG, RA, DEC, VMAG, RAV, and DECV. The SphericalAZFPA
state type is composed of the following elements: RMAG, RA, DEC, VMAG, AZI and FPA. The
tables and figures below describe each spherical state element in detail including singularities.
Geometry of the Spherical Elements
Name
Description
RMAG
The magnitude of the position vector.
RA
The right ascension which is the angle between the projection of the position vector
into the xy-plane and the x-axis measured counterclockwise.
DEC
The declination which is the angle between tjhe position vector and the xy-plane.
VMAG
The magnitude of the velocity vector.
FPA
The vertical flight path angle. The angle measured from a plane normal to the postion
vector to the velocity vector , measured in the plane formed by position vector and
velocity vector.
AZI
The flight path azimuth. The angle measured from the vector perpendicular to the
position vector and pointing north, to the projection of the velocity vector, into a
plane normal to the position vector.
RAV
The right ascension of velocity. The angle between the projection of the velocity vector into the xy-plane and the x-axis measured counterclockwise.
DECV
The flight path azimuth. The angle between the velocity vector and the xy-plane.
599
Reference Guide
Spacecraft Orbit State
Singularities in the Spherical Elements
Singularity
Comments and Behavior
RMAG = 0
Results in a singular conic section: declination and flight path angle are
undefined. GMAT will not allow transformations if RMAG < 1e-10. For
RMAG values greater than, but near 1e-10, loss of precision may occur
in transformations.
VMAG = 0
Results in a singular conic section: velocity declination and flight path
angle are undefined. GMAT will not allow transformations if VMAG <
1e-10.For VMAG values greater than, but near 1e-10, loss of precision
may occur in transformations.
Planetodetic State Type
The Planetodetic state type is useful for specifying states relative to the surface of a central body.
It is very similar to the spherical state types, but uses the central body's flattening in its definition.
To use the Planetodetic state type, the spacecraft’s coordinate system must have a celestial body at
the origin, and must have BodyFixed axes.
600
Element
Description
PlanetodeticRMAG
Magnitude of the orbital radius vector.
PlanetodeticLON
Planetodetic longitude.
PlanetodeticLAT
Planetodetic latitude, using the Flattening of the central body.
PlanetodeticVMAG
Magnitude of the orbital velocity vector in the fixed frame.
PlanetodeticAZI
Orbital velocity azimuth in the fixed frame.
PlanetodeticHFPA
Horizontal flight path angle. HFPA = 90 - VFPA
Spacecraft Orbit State
Reference Guide
Singularities in the Planetodetic Elements
Singularity
Comments and Behavior
PlanetodeticRMAG = Results in a singular conic section: declination and flight path angle are
0
undefined. GMAT will not allow transformations if PlanetodeticRMAG
< 1e-10. For PlanetodeticRMAG values greater than, but near 1e-10, loss
of precision may occur in transformations.
PlanetodeticVMAG = Results in a singular conic section: velocity declination and flight path an0
gle are undefined. GMAT will not allow transformations if PlanetodeticVMAG < 1e-10. For PlanetodeticVMAG values greater than, but near
1e-10, loss of precision may occur in transformations.
Equinoctial State Type
GMAT supports the Equinoctial state representation which is non-singular for elliptic orbits with
inclinations less than 180 degrees. To use the Equinoctial state type, the spacecraft’s coordinate
system must have a central body at the origin.
Element
Description
SMA
See Keplerian section.
EquinoctialH
A measure of the orbital eccentricity and argument of periapsis.
EquinoctialH and EquinoctialK together govern how elliptical
an orbit is and where the periapsis is located. EquinotialH =
ECC * sin(AOP).
EquinoctialK
A measure of the orbital eccentricity and argument of periapsis.
EquinoctialH and EquinoctialK together govern how eliptical
an orbit is and where the periapsis is located. EquinotialK = ECC
* cos(AOP)
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).
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).
MLONG
A measure of the mean location of the spacecraft in its orbit.
MLONG = AOP + RAAN + MA.
Singularities in the Equinoctial Elements
Element
Description
INC = 180
RAAN is undefined. If INC > 180 - 1.0e-11, GMAT sets RAAN
to 0 degrees. GMAT does not support Equinoctial elements for
true retrograde orbits.
ECC > 0.9999999
Equinoctial elements are not defined for parabolic or hyperbolic
orbits.
601
Reference Guide
Spacecraft Orbit State
Alternate Equinoctial State Type
The AlternateEquinoctial state type is a slight variation on the Equinoctial elements that uses
sin(INC/2) instead of tan(INC/2) in the "P" and "Q" elements. Both representations have the same
singularties.
Element
Description
SMA
See Keplerian section.
EquinoctialH
See Equinoctial section.
EquinoctialK
See Equinoctial section.
AltEquinoctialP
A measure of the orientation of the orbit. AltEquinoctialP and
AltEquinoctialQ together govern how an orbit is oriented. AltEquinotialP = sin(INC/2)*sin(RAAN).
AltEquinoctialQ
A measure of the orientation of the orbit. AltEquinoctialP and
AltEquinoctialQ together govern how an orbit is oriented. AltEquinotialP = sin(INC/2)*cos(RAAN).
MLONG
See Equinoctial section.
Modified Equinoctial State Type
The ModifiedEquinoctial state representation is non-singular for circular, elliptic, parabolic, and
hyperbolic orbits. The only singularity is for retrograde equatorial orbits, because, like Equinoctial
and ModifiedEquinoctial, GMAT does not support the retrograde factor.
Element
Description
SemilatusRectum
Magnitude of the position vector when at true anomaly of 90 deg
SemilatusRectum = SMA*(1-ECC^2)
ModEquinoctialF
Components of eccentricity vector (with ModEquinoctialG).
Projection of eccentricity vector onto x. ModEquinoctialF =
ECC * cos (AOP+RAAN)
ModEquinoctialG
Components of eccentricity vector (with ModEquinoctialF).
Projection of eccentricity vector onto y. ModEquinoctialG =
ECC * sin (AOP+RAAN)
ModEquinoctialH
Identical to EquinoctialQ.
ModEquinoctialK
Idential to EquinoctialP.
TLONG
A measure of the true location of the spacecraft in its orbit.
TLONG = AOP + RAAN + TA.
Singularities in the Modified Equinoctial Elements
602
Element
Description
INC = 180
Similar to Equinoctial elements, there is singularity at INC = 180
deg. GMAT does not support ModifiedEquinoctial elements for
retrograde equatorial orbits.
Spacecraft Orbit State
Reference Guide
Hyperbolic Asymptote State Type
GMAT supports two related hyperbolic asymptote state types: IncomingAsymptote for defining
the incoming hyperbolic asymptote, and OutgoingAsymptote, for defining the outgoing hyperbolic
asymptote. Both representations are useful for defining flybys.
Element
Description
IncomingRadPer
The orbital radius of periapsis. The radius of periapsis is the minimum distance (osculating) between the spacecraft and celestial
body at the origin of coordinate system. IncomingRadPer/OutgoingRadPer differ from RadPer only in that they are associated
with the IncomingAsymptote and OutgoingAsymptote state
representations, respectively.
OutgoingRadPer
IncomingC3Energy
OutgoingC3Energy
IncomingRHA
OutgoingRHA
IncomingDHA
OutgoingDHA
IncomingBVAZI
C3 energy. C3Energy = -mu/SMA. IncomingC3Energy/
OutgoingC3Energy differ only in that they are associated with
the IncomingAsymptote and OutgoingAsymptote state representations, respectively.
IncomingRHA/OutgoingRHA is the right ascension of the incoming/outgoing asymptote. If C3Energy < 0 the apsides vector
is substituted for the incoming/outgoing asymptote.
IncomingDHA/OutgoingDHA is the declination of the incoming/outgoing asymptote. If C3Energy < 0 the apsides vector is
substituted for the incoming/outgoing asymptote..
OutgoingBVAZI
IncomingBVAZI/OutgoingBVAZI is the B-vector azimuth at
infinity of the incoming/outgoing asymptote measured counterclockwise from south. If C3Energy < 0 the apsides vector is substituted for the outgoing/incoming asymptote.
TA
See Keplerian.
Singularities in the Hyperbolic Asymptote Elements
Element
Description
IncomingC3Energy/
OutgoingC3Energy = 0
If IncomingC3Energy/OutgoingC3Energy = 0 the spacecraft has a parabolic orbit. Hyperbolic asymptote states do
not support parabolic orbits. It must be avoided that -1E-7 ≤
IncomingC3Energy/OutgoingC3Energy ≤ 1E-7 by choosing
a proper set of elements.
ECC = 0
For the case of circular orbits, TA is undefined. It must be avoided
that ECC ≤ 1E-7 by choosing a proper set of elements. GMAT
does not support hyperbolic asymptote representation for true circular orbits.
Asymptote vector parallel to If the asymptote vector is parallel or antiparallel to coordinate
z-axis
system’s z-direction, then the B-plane is undefined. It must be
avoided by choosing either a proper coordinate system or set of
elements.
603
Reference Guide
Spacecraft Orbit State
State Component Interactions with the Spacecraft Coordinate System
Field
When you define Spacecraft state elements such as SMA, X, or DEC for example, these values are
set in coordinates defined by the Spacecraft’s CoordinateSystem field. For example, the following
lines result in the X-component of the Cartesian state of MySat to be 1000, in the EarthFixed
system.
aSpacecraft.CoordinateSystem = EarthFixed
aSpacecraft.X = 1000
When the script lines above are executed in a script, GMAT converts the state to the specified
coordinate system, in this case EarthFixed, sets the X component to 1000, and then converts the
state back to the internal inertial representation.
The following example sets SMA to 8000 in the EarthMJ2000Eq system, then sets X to 6000
in the Earth fixed system. (Note this is NOT allowed in initialization mode; see later remarks for
more information).
aSpacecraft.CoordinateSystem = EarthMJ2000Eq
aSpacecraft.SMA = 8000
aSpacecraft.CoordinateSystem = EarthFixed
aSpacecraft.X = 6000
State Component Interactions with the Spacecraft Epoch Field
When you specify the Spacecraft’s epoch, you define the initial epoch of the spacecraft in the specified coordinate system. If your choice for the Spacecraft's coordinate system is a time varying system such as the EarthFixed system, then you define the state in the EarthFixed system at that
epoch. For example, the following lines would result in the cartesian state of MySat to be set to
[7000 0 1300 0 7.35 1] in the EarthFixed system at 01 Dec 2000 12:00:00.000 UTC.
Create Spacecraft MySat
MySat.Epoch.UTCGregorian = '01 Dec 2000 12:00:00.000'
MySat.CoordinateSystem = EarthFixed
MySat.X = 7000
MySat.Y = 0
MySat.Z = 1300
MySat.VX = 0
MySat.VY = 7.35
MySat.VZ = 1
The corresponding EarthMJ2000Eq representation is
X
Y
Z
VX
VY
VZ
604
= -2320.30266
= -6604.25075
= 1300.02599
= 7.41609
= -2.60562
= 0.99953
Spacecraft Orbit State
Reference Guide
You can change the epoch of a Spacecraft in the mission sequence using a script line like this:
MySat.Epoch.TAIGregorian = '02 Dec 2000 12:00:00.000'
When the above line is executed in the mission sequence, GMAT converts the state to the specified
coordinate system and then to the specified state type — in this case EarthFixed and Cartesian
respectively — sets the epoch to the value of 02 Dec 2000 12:00:00.000, and then converts
the state back to the internal representation. This behavior is identical to that of the spacecraft orbit
dialog box in the GUI. Because the coordinate system in this case is time varying, changing the
spacecraft epoch has resulted in a change in the spacecraft's inertial state representation. After the
epoch is changed to 02 Dec 2000 12:00:00.000, the EarthMJ2000Eq state representation
is now:
X
Y
Z
VX
VY
VZ
= -2206.35771
= -6643.18687
= 1300.02073
= 7.45981
= -2.47767
= 0.99953
Scripting Limitations during Initialization
When setting the Spacecraft orbit state in a script, there are a few limitations to be aware of. In the
initialization portion of the script (before the BeginMissionSequence command), you should set
the epoch and coordinate system only once; multiple definitions of these parameters will result in
either errors or warning messages and may lead to unexpected results.
Also when setting a state during initialization, you must set the orbit state in a set of fields corresponding to a single state type. For example, set the orbit state using the X, Y, Z, VX, VY, VZ fields
(for the Cartesian state type) or the SMA, ECC, INC, RAAN, AOP, TA fields (for the Keplerian
state type), but not a mixture of the two. If you need to mix state types, coordinate systems, or epochs
to define the state of a spacecraft, you must set the state using scripting in the mission sequence
(after the BeginMissionSequence command).
Shared State Components
Some state components, such as SMA, are shared among multiple state representations. In the mission sequence, GMAT does not require you to specify the state representation that you are setting;
rather, you may specify a combination of elements from different representations.
For these shared components, GMAT defines a default representation for each, and uses that representation when setting or retrieving the value for the shared component. This is normally transparent, though it can have side effects if the default representation has singularities or numerical
precision losses caused by the value being set or retrieved. The following table lists each shared state
component and its default representation.
Field
Shared Between
Default Representation
AOP
Keplerian, ModifiedKeplerian
Keplerian
DEC
SphericalAZFPA, SphericalRADEC
SphericalAZFPA
605
Reference Guide
Spacecraft Orbit State
Field
Shared Between
Default Representation
EquinoctialH
AlternateEquinoctial, Equinoctial
Equinoctial
EquinoctialK
AlternateEquinoctial, Equinoctial
Equinoctial
INC
Keplerian, ModifiedKeplerian
Keplerian
RA
SphericalAZFPA, SphericalRADEC
SphericalAZFPA
RAAN
Keplerian, ModifiedKeplerian
Keplerian
RMAG
SphericalAZFPA, SphericalRADEC
SphericalAZFPA
SMA
AlternateEquinoctial, Equinoctial, Ke- Keplerian
plerian
TA
IncomingAsymptote,
OutgoingAs- Keplerian
ymptote, Keplerian, ModifiedKeplerian
VMAG
SphericalAZFPA, SphericalRADEC
SphericalAZFPA
As an example, consider the following mission sequence. Because GMAT executes each command
sequentially, it uses the assigned state representation to calculation each component. For shared
components, it uses the default representation for reach.
BeginMissionSequence
aSpacecraft.SMA = 20000
%
aSpacecraft.RA = 30
%
aSpacecraft.OutgoingDHA = 90 %
aSpacecraft.TA = 45
%
conversion
conversion
conversion
conversion
goes
goes
goes
goes
through
through
through
through
Keplerian
SphericalAZFPA
OutgoingAsymptote
Keplerian
Warning
When setting state parameters (especially in Keplerian-based representations) using
non-default dependencies, be careful of the loss of precision caused by large translations
in the intermediate orbit.
Examples
Define a Spacecraft’s Earth MJ2000Eq coordinates in the Keplerian representation:
Create Spacecraft aSpacecraft
aSpacecraft.CoordinateSystem = EarthMJ2000Eq
aSpacecraft.SMA = 7100
aSpacecraft.ECC = 0.01
aSpacecraft.INC = 30
aSpacecraft.RAAN = 45
aSpacecraft.AOP = 90
aSpacecraft.TA
= 270
Define a Spacecraft’s Earth fixed coordinates in the Cartesian representation:
Create Spacecraft aSpacecraft
606
Spacecraft Orbit State
Reference Guide
aSpacecraft.CoordinateSystem = EarthFixed
aSpacecraft.X = 7100
aSpacecraft.Y = 0
aSpacecraft.Z = 1300
aSpacecraft.VX = 0
aSpacecraft.VY = 7.35
aSpacecraft.VZ = 1
Define a Spacecraft’s Moon centered coordinates in ModifiedKeplerian representation.
Create CoordinateSystem MoonInertial
MoonInertial.Origin = Luna
MoonInertial.Axes = BodyInertial
Create Spacecraft aSpacecraft
aSpacecraft.CoordinateSystem = MoonInertial
aSpacecraft.RadPer = 2100
aSpacecraft.RadApo = 2200
aSpacecraft.INC = 90
aSpacecraft.RAAN = 45
aSpacecraft.AOP = 45
aSpacecraft.TA = 180
Define a Spacecraft’s Rotating Libration Point coordinates in the SphericalAZFPA representation:
Create LibrationPoint ESL1
ESL1.Primary = Sun
ESL1.Secondary = Earth
ESL1.Point = L1
Create CoordinateSystem EarthSunL1CS
EarthSunL1CS.Origin = ESL1
EarthSunL1CS.Axes = ObjectReferenced
EarthSunL1CS.XAxis = R
EarthSunL1CS.ZAxis = N
EarthSunL1CS.Primary = Sun
EarthSunL1CS.Secondary = Earth
Create Spacecraft aSpacecraft
aSpacecraft.CoordinateSystem = EarthSunL1CS
aSpacecraft.DateFormat = UTCGregorian
aSpacecraft.Epoch = '09 Dec 2005 13:00:00.000'
aSpacecraft.RMAG = 1520834.130720907
aSpacecraft.RA = -111.7450242065574
aSpacecraft.DEC = -20.23326432189756
aSpacecraft.VMAG = 0.2519453702907011
aSpacecraft.AZI = 85.22478175803107
aSpacecraft.FPA = 97.97050698644287
Define a Spacecraft’s Earth-fixed coordinates in the Planetodetic representation:
607
Reference Guide
Spacecraft Orbit State
Create Spacecraft aSpacecraft
aSpacecraft.CoordinateSystem = EarthFixed
aSpacecraft.PlanetodeticRMAG = 7218.032973047435
aSpacecraft.PlanetodeticLON = 79.67188405817301
aSpacecraft.PlanetodeticLAT = 10.43478253417053
aSpacecraft.PlanetodeticVMAG = 6.905049647178043
aSpacecraft.PlanetodeticAZI = 81.80908019170981
aSpacecraft.PlanetodeticHFPA = 1.494615714741736
Set a Spacecraft’s Earth MJ2000 ecliptic coordinates in the Equinoctial representation:
Create Spacecraft aSpacecraft
aSpacecraft.CoordinateSystem = EarthMJ2000Ec
aSpacecraft.SMA = 9100
aSpacecraft.EquinoctialH = 0.00905
aSpacecraft.EquinoctialK = 0.00424
aSpacecraft.EquinoctialP = -0.1059
aSpacecraft.EquinoctialQ = 0.14949
aSpacecraft.MLONG = 247.4528
608
Reference Guide
Spacecraft Visualization Properties
The visual properties of the spacecraft
Description
The Spacecraft Visualization Properties lets you define a spacecraft model, translate the spacecraft in X,Y, Z directions or apply a fixed rotation to the attitude orientation of the model. You
can also adjust the scale factor of the spacecraft model size. GMAT lets you set orbit colors via the
spacecraft visualization properties as well. You can set colors to spacecraft orbital trajectories and
any perturbing trajectories that are drawn during iterative processes. See Color documentation for
discussion and examples on how to set orbital colors using Spacecraft object's OrbitColor and TargetColor fields. Also see the Fields section below to read more about these two fields. The Spacecraft visualization properties can be configured either through GMAT’s GUI or the script interface.
See Also: OrbitView, Color
Fields
Field
Description
ModelOffsetX
This field lets you translate a spacecraft in +X or -X axis of central body's
coordinate system.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
ModelOffsetY
Allows you to translate a spacecraft in +Y or -Y axis of central body's
coordinate system.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
ModelOffsetZ
Real
-3.5 <= Real <= 3.5
set
0.000000
N/A
GUI, script
Real
-3.5 <= Real <= 3.5
set
0.000000
N/A
GUI, script
Allows you to translate a spacecraft in +Z or -Z axis of central body's
coordinate system.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
Real
-3.5 <= Real <= 3.5
set
0.000000
N/A
GUI, script
609
Reference Guide
Spacecraft Visualization Properties
Field
Description
ModelRotationX
Allows you to perform a fixed rotation of spacecraft's attitude w.r.t X-axis
of central body's coordinate system.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
ModelRotationY
Allows you to perform a fixed rotation of spacecraft's attitude w.r.t Y-axis
of central body's coordinate system.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
ModelRotationZ
Real
0.001 <= Real <= 1000
set
3.000000
N/A
GUI, script
Allows you to load spacecraft models that are in .3ds model formats.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
610
Real
-180 <= Real <= 180
set
0.000000
Deg.
GUI, script
Allows you to apply a scale factor to the spacecraft model's size.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
ModelFile
Real
-180 <= Real <= 180
set
0.000000
Deg.
GUI, script
Allows you to perform a fixed rotation of spacecraft's attitude w.r.t Z-axis
of central body's coordinate system.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
ModelScale
Real
-180 <= Real <= 180
set
0.000000
Deg.
GUI, script
String
. 3ds spacecraft model formats only
set
../data/vehicle/models/aura.3ds
N/A
GUI, script
Spacecraft Visualization Properties
Reference Guide
Field
Description
OrbitColor
Allows you to set available colors on spacecraft orbits. The spacecraft
orbits are drawn using the OrbitView graphics displays. The colors can
be identified through a string or an integer array. For example: Setting spacecraft's orbit color to red can be done in following two ways:
DefaultSC.OrbitColor = Red or DefaultSC.OrbitColor =
[255 0 0]. This field can be modified in the Mission Sequence as well.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
TargetColor
Integer Array or String
Any color available from the Orbit Color Picker in
GUI. Valid predefined color name or RGB triplet
value between 0 and 255.
set
Red
N/A
GUI, script
Allows you to set available colors on a spacecraft's perturbing trajectories
during iterative processes such as Differential Correction or Optimization.
The perturbing trajectories are drawn through the OrbitView resource.
The target color can be identified through a string or an integer array. For
example: Setting spacecraft's perturbing trajectories to yellow color can be
done in following two ways: DefaultSC.TargetColor = Yellow
or DefaultSC.TargetColor = [255 255 0] . This field can be
modified in the Mission Sequence as well.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
Integer Array or String
Any color available from the Orbit Color Picker in
GUI. Valid predefined color name or RGB triplet
value between 0 and 255.
set
Teal
N/A
GUI, script
GUI
The figure below shows the default settings for the Spacecraft Visualization Properties resource:
611
Reference Guide
Spacecraft Visualization Properties
The GUI interface for Spacecraft Visualization Properties is contained on the Visualization tab
of the Spacecraft resource. You can configure visualization properties of the spacecraft and visualize
the changes in the Display window.
Within the Display window, you can Left click and drag your mouse to change camera orientation.
Camera orientation can be changed in Up/Down/Left/Right directions. You can also Right click
and drag your mouse to zoom in and out of the Display window. Right click and moving the cursor
in Up direction helps to zoom out and moving the cursor in Down direction helps to zoom in.
Remarks
Configuring Spacecraft Visualization Properties
GMAT lets you define any spacecraft model but currently GMAT supports only .3ds model format.
Several .3ds spacecraft model formats are available here. You can also download more .3ds models
by clicking here. Most of these models are in .3ds format, which can be read by most 3D programs.
GMAT lets you apply fixed rotation to the attitude orientation of the spacecraft model or translate the
model in any of the X, Y and Z directions. You can also apply a scale factor to the selected spacecraft
model to adjust the size of the model. Any changes that are made to the spacecraft model, attitude
orientation, translation or scale size factor will also be displayed in OrbitView resource’s graphics
window. The configured spacecraft visualization properties will only show up in OrbitView graphics
window after you have run the mission. See OrbitView resource’s user-specification document to
learn more about OrbitView graphics window.
612
Spacecraft Visualization Properties
Reference Guide
Examples
This example shows you how to configure Spacecraft Visualization Properties resource. All values
are non-default values.
Create Spacecraft aSat
aSat.ModelFile = '../data/vehicle/models/aura.3ds'
aSat.ModelOffsetX = 1.5
aSat.ModelOffsetY = -2
aSat.ModelOffsetZ = 3
aSat.ModelRotationX = 180
aSat.ModelRotationY = 180
aSat.ModelRotationZ = 90
aSat.ModelScale = 15
Create Propagator aProp
Create OrbitView anOrbitView
anOrbitView.Add = {aSat, Earth}
BeginMissionSequence
Propagate aProp(aSat) {aSat.ElapsedSecs = 9000}
613
614
Reference Guide
StatisticsAcceptFilter
Allows selection of data subsets for processing by the batch least squares estimator.
Description
The StatisticsAcceptFilter object is used to create criteria for the inclusion of subsets of the available data in the estimation process based on observation frequency, tracker, measurement type, or
time. Instances of StatisticsAcceptFilter are specified for use on the DataFilters field of a TrackingFileSet object. A single StatisticsAcceptFilter may employ multiple selection criteria (for example simultaneously thinning different stations or data types by differing intervals). Multiple criteria
on a single filter are considered in an AND sense. When multiple criteria are specified on a single
filter, an observation must meet all specified criteria to be accepted.
Multiple StatisticsAcceptFilters with different selection criteria may be specified on a single TrackingFileSet. When multiple filters are specified, these act in an OR sense. Data meeting criteria for
any of the specified filters will be accepted.
See Also StatisticsRejectFilter, TrackingFileSet
Fields
Field
Description
DataTypes
List of data types
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
EpochFormat
String Array
Range_RU, Doppler_Hz, or All
set
{All}
N/A
script
Allows user to select format of the epoch
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
String
UTCGregorian, UTCModJulian, TAIGregorian, TAIModJulian, TTGregorian, TTModJulian A1Gregorian, A1ModJulian, TDBGregorian,
TDBModJulian
set
TAIModJulian
N/A
script
615
Reference Guide
StatisticsAcceptFilter
Field
Description
InitialEpoch
Initial epoch of desired data to process
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
FinalEpoch
Final epoch of desired data to process
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
FileNames
Access
Default Value
Units
Interfaces
StringArray
valid
file
name,
'From_AddTrackingConfig'
set
{All}
N/A
script
'All',
or
List of user-created tracked objects (e.g., name of the Spacecraft resource
being tracked)
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
616
String
any valid epoch
set
latest day defined in GMAT
N/A
script
List of file names (a subset of the relevant TrackingFileSet's
FileName field) containing the tracking data. If this field equals
From_AddTrackingConfig, then two things happen; (1) All of the files in
the relevant TrackingFileSet are used as a starting point, and (2) Of the
data in all of the files, only the data defined by the AddTrackingConfig
field of the relevant TrackingFileSet are used.
Data Type
Allowed Values
ObservedObjects
String
any valid epoch
set
earliest day defined in GMAT
N/A
script
Object Array
User defined observed object or 'All'
set
{All}
N/A
script
StatisticsAcceptFilter
Reference Guide
Field
Description
Trackers
List of user-created trackers (e.g., name of the GroundStation resource
being used)
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
ThinningFrequency
If ThinMode is Frequency, the integer 'n' is used to specify that every
nth data point should be accepted. For example, 3 specifies that every
third data point, meeting all the accept criteria, should be accepted and 1
specifies that every data point, meeting all the accept criteria, should be
accepted. If ThinMode is Time, the integer 'n' is a number of seconds
between accepted observations, using the first available observation as the
anchor epoch. For example, a value of 300 means that observations will be
accepted every 300 seconds, starting from the first available observation.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
ThinMode
Object Array
any valid user-created Tracker object (e.g.,
GroundStation) or 'All'
set
{All}
N/A
script
Integer
Positive Integer
set
1
Depends on ThinMode value
script
"Frequency" for record count frequency mode and "Time" for time window frequency mode
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
String
"Frequency" or "Time"
set
Frequency
N/A
script
Examples
The StatisticsAcceptFilter object should be assigned to the DataFilters field of a TrackingFileSet. This example shows how to create a StatisticsAcceptFilter to sample the data at a frequency of 1:10 (thinning the data to one tenth of its volume).
Create StatisticsAcceptFilter saf;
saf.ThinningFrequency = 10;
Create TrackingFileSet estData;
617
Reference Guide
StatisticsAcceptFilter
estData.DataFilters = {saf};
BeginMissionSequence;
The next example will accept all data from station GDS and accept every 5th observation from
station CAN. Only data from stations GDS and CAN will be accepted.
Create StatisticsAcceptFilter saf1;
Create StatisticsAcceptFilter saf2;
Create GroundStation GDS CAN;
saf1.Trackers
= {'GDS'};
saf2.Trackers
= {'CAN'};
saf2.ThinningFrequency = 5;
Create TrackingFileSet estData;
estData.DataFilters = {saf1, saf2};
BeginMissionSequence;
The last example illustrates thinning data by time interval, using a 300-second thinning interval.
Create StatisticsAcceptFilter saf;
saf.ThinMode
= 'Time';
saf.ThinningFrequency = 300;
Create TrackingFileSet estData;
estData.DataFilters = {saf};
BeginMissionSequence;
618
Reference Guide
StatisticsRejectFilter
Allows selection of data subsets for processing by the batch least squares estimator.
Description
The StatisticsRejectFilter object is used to create criteria for the exclusion of subsets of the available
data in the estimation process based on tracker, observed object, measurement type, or time. A single
StatisticsRejectFilter may employ multiple selection criteria (for example simultaneous thinning by
time and tracker). Multiple criteria on a single filter are considered in an AND sense. When multiple
criteria are specified in a single filter, an observation must meet all specified criteria to be rejected.
Instances of StatisticsRejectFilter are specified for use on the DataFilters field of a TrackingFileSet object. Multiple filters with different selection criteria may be specified on a single TrackingFileSet. When multiple filters are specified, these act in an OR sense. Data meeting criteria for
any of the specified filters will be rejected.
See Also StatisticsAcceptFilter, TrackingFileSet
Fields
Field
Description
DataTypes
List of data types
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
EpochFormat
Allows user to select format of the epoch
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
InitialEpoch
String Array
Range_RU, Doppler_Hz, or All
set
{All}
N/A
script
String
UTCGregorian, UTCModJulian, TAIGregorian, TAIModJulian, TTGregorian, TTModJulian A1Gregorian, A1ModJulian, TDBGregorian,
TDBModJulian
set
TAIModJulian
N/A
script
Initial epoch of desired data to process
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
String
any valid epoch
set
earliest day defined in GMAT
N/A
script
619
Reference Guide
StatisticsRejectFilter
Field
Description
FinalEpoch
Final epoch of desired data to process
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
FileNames
List of file names (a subset of the relevant TrackingFileSet's FileName
field) containing the tracking data, to be excluded from processing.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
ObservedObjects
StringArray
valid file name or 'All'
set
{All}
N/A
script
List of user-created tracked objects (e.g., name of the Spacecraft resource
being tracked)
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
Trackers
String
any valid epoch
set
latest day defined in GMAT
N/A
script
Object Array
User defined observed object or 'All'
set
{All}
N/A
script
List of user-created trackers (e.g., name of the GroundStation resource
being used)
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
Object Array
any valid user-created Tracker object (e.g.,
GroundStation) or 'All'
set
{All}
N/A
script
Examples
The StatisticsRejectFilter object should be assigned to the DataFilters field of a TrackingFileSet.
This example shows how to create a StatisticsRejectFilter to reject all observations from station
GDS.
Create GroundStation GDS;
Create StatisticsRejectFilter srf;
srf.Trackers
= {'GDS'};
620
StatisticsRejectFilter
Reference Guide
Create TrackingFileSet estData;
estData.DataFilters = {srf};
BeginMissionSequence;
The next example will reject all DSN Doppler (i.e., Doppler_HZ) tracking measurements from station GDS, and all tracking of any type from station CAN. All other tracking measurements will be
accepted.
Create GroundStation GDS CAN;
Create StatisticsRejectFilter srf1;
Create StatisticsRejectFilter srf2;
srf1.Trackers
srf1.DataTypes
srf2.Trackers
= {'GDS'};
= {'Doppler_HZ'};
= {'CAN'};
Create TrackingFileSet estData;
estData.DataFilters = {srf1, srf2};
BeginMissionSequence;
621
622
Reference Guide
String
A user-defined string variable
Description
The String resource is used to store a string value for use by commands in the Mission Sequence.
In the script environment, String resources are initialized to the string
'STRING_PARAMETER_UNDEFINED' on creation. In the GUI environment, they’re initialized to
the empty string (''). String resources can be assigned using string literals or (in the Mission Sequence) other String resources, numeric Variable resources, or resource parameters that have string
types.
See Also: Array, Variable
Fields
The String resource has no fields; instead, the resource itself is set to the desired value.
Field
Description
value
The value of the string variable.
Data Type
Allowed Values
Access
Default Value
String
N/A
set, get
'' (empty) (GUI)
Units
Interfaces
'STRING_PARAMETER_UNDEFINED' (script)
N/A
GUI, script
GUI
The GMAT GUI lets you create multiple String resources at once without leaving the window. To
create a String:
623
Reference Guide
String
1. In the String Name box, type the desired name of the string.
2. In the String Value box, type the initial value of the string. This is required and must be a literal
string value. Quotes are not necessary when setting the value.
3. Click the => button to create the string and add it to the list on the right.
You can create multiple String resources this way. To edit an existing string in this window, click it
in the list on the right and edit the value. You must click the => button again to save your changes.
You can also double-click an existing String in the resources tree in the main GMAT window. This
opens the string properties box above that allows you to edit the value of that individual string.
Remarks
String resources can (in the Mission Sequence) be set using numeric Variable resources. The numeric value of the Variable is converted to a string during the assignment. The numeric value is
converted to a string representation in either floating-point or scientific notation (whichever is more
appropriate) with a maximum of 16 significant figures.
Examples
Creating a string and assigning it a literal value:
Create ReportFile aReport
Create String aStr
aStr = 'MyString'
BeginMissionSequence
Report aReport aStr
624
Reference Guide
TrackingFileSet
Manages the observation data contained in one or more external tracking data files.
Description
A TrackingFileSet is required for both simulator and estimator runs. For a data simulation run, the
user must specify the desired tracking strings for the simulated data (via AddTrackingConfig) and
provide an output file name for the simulated tracking observations (via FileName). In simulation
mode, the user may specify a range modulo constant, Doppler count interval, and other parameters,
depending on the type of tracking data being simulated. See the remarks below for more details.
When running the estimator, the FileName parameter specifies the path to a pregenerated external
tracking data file. It is not necessary to explicitly specify tracking configurations when running the
estimator; GMAT will examine the specified external tracking data file and determine the tracking
configurations automatically. GMAT will throw an error message if it is unable to uniquely identify
all objects found in the tracking data file.
When running the estimator, one or more StatisticsAcceptFilters and/or StatisticsRejectFilters
may be employed to select from all available observations a smaller subset for use in the estimation
process.
The SimRangeModuloConstant and SimDopplerCountInterval fields apply only to the simulator and are ignored by the estimator. When running the estimator, these values are provided in the
tracking data file. For both the simulator and estimator, relativity, light time, and ET-TAI corrections
may optionally be applied.
See Also: Simulator, BatchEstimatorInv, StatisticsAcceptFilter, StatisticsRejectFilter
Fields
Field
Description
AddTrackingConfig
One or more signal paths and measurement types for simulation or estimation. See notes and examples for details.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
String
{{<XMIT_GroundStation>,
<RECV_GroundStation>},
Type1[, MeasurementType2]}
set
None
N/A
script
<Spacecraft>,
Measurement-
625
Reference Guide
TrackingFileSet
Field
Description
DataFilters
Defines filters to be applied to the data. One or more filters of either type
(StatisticsAcceptFilter, StatisticsRejectFilter) may be specified.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
FileName
For simulation, specifies an output file for the simulated measurement data. For estimation, specifies one or more preexisting tracking data input
files in GMD-format.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
RampTable
Resource
User defined instances of StatisticsAcceptFilter
and StatisticsRejectFilter resources
set
None
N/A
script
String
Valid file path
set
None
N/A
script
Specifies a transmit frequency ramp table to be used when computing measurements for both simulation and estimation.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
String
Valid file path
set
None
N/A
script
SimDopplerCountIn- Specifies the Doppler count interval used for Doppler measurements. This
terval
value is only used in simulation mode.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
626
Real
Real > 0
set
1.0
Seconds
script
TrackingFileSet
Reference Guide
Field
Description
SimRangeModuloConstant
Specifies the value of the maximum DSN Range value. This value is only
used in simulation mode.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
UseETminusTAI
Flag specifying if General Relativistic time corrections should be made
to the measurements. If this flag is set, GMAT will apply the adjustment
from TAI to Ephemeris Time when solving the light time equations for
the computed measurement.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
UseLightTime
Real
Real > 0
set
1.00E+18
Range Units (RU)
script
Boolean
True, False
set
False
N/A
script
Flag specifying whether light time corrections should be applied to computed measurements.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
Boolean
True, False
set
True
N/A
script
UseRelativityCorrec- Flag specifying if General Relativistic corrections should be made to the
tion
computed measurements. If this flag is set, GMAT will adjust the computed light time to include the effects due to the coordinate velocity of light
and bending of the signal path.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
Boolean
True, False
set
False
N/A
script
Remarks
The SimRangeModuloConstant field is used only in the simulation of DSN range tracking data.
The user may specify a value to be used for this field or may omit it, in which case the default value
is used. This field is not applicable to estimation. In estimation, this value is provided in the input
tracking data file.
627
Reference Guide
TrackingFileSet
The SimDopplerCountInterval is used in the simulation of DSN Doppler tracking data. The user
may specify a value to be used for this field or may omit it, in which case default value of 1 second
is used. This field is not applicable to estimation. In estimation, this value is provided in the input
tracking data file.
When displaying or saving a TrackingFileSet object using the Write command, GMAT will display
a number of items relevant to simulating TDRS data formats. These options are not implemented
in the current release and should be ignored or manually removed from the output file.
Measurement Types Supported
Currently, GMAT supports the following ramped or non-ramped measurement types using either
X-band or S-band only.
• DSN Sequential Ranging (TRK-2-34 data Type 7)
• Derived "Doppler" type measurement obtained using successive DSN Total Count Phase
(TRK-2-34 data Type 17) measurements
Measurement Type Names
Currently the measurement type names used to identify observation types in GMD data files and
on the TrackingFileSet.AddTrackingConfig object field are not the same as those used to build
measurement error models for those types. Use the following table as a guide.
GMD File and
TrackingFileSet.AddTrackingConfig
Measurement Type Name
ErrorModel Measurement Type Name
DSNRange
Range_RU
Doppler
Doppler_HZ
Examples
This example illustrates use of the TrackingFileSet object. Specification of the tracking configurations (AddTrackingConfig) is optional when running the estimator. If omitted, GMAT will attempt
to automatically detect the tracking configurations present in the tracking data file.
In this example, the frequency ramp table file dsn.ramp must be a preexisting ramp table. GMAT
will not simulate ramp table records. Alternatively, the user may omit specification of a ramp table
when simulating data. If the ramp table is omitted, the simulator will use the frequency specified on
the Transmitter object attached to each GroundStation.
Create TrackingFileSet dsnObs;
%Create objects referenced by dnsObs
Create GroundStation GDS CAN MAD;
Create Spacecraft EstSat;
Create StatisticsAcceptFilter saf;
dsnObs.AddTrackingConfig
dsnObs.AddTrackingConfig
dsnObs.AddTrackingConfig
dsnObs.FileName
628
=
=
=
=
{{GDS, EstSat, GDS}, 'Doppler'};
{{CAN, EstSat, CAN}, 'Doppler'};
{{MAD, EstSat, MAD}, 'Doppler', 'Range_KM'};
{'dsn.gmd'};
TrackingFileSet
Reference Guide
dsnObs.RampTable
dsnObs.UseLightTime
dsnObs.UseRelativityCorrection
dsnObs.UseETminusTAI
dsnObs.SimRangeModuloConstant
dsnObs.SimDopplerCountInterval
dsnObs.DataFilters
=
=
=
=
=
=
=
{'dsn.ramp'};
True;
False;
False;
67108864;
10.;
{saf};
BeginMissionSequence;
GMAT Tracking Data File Format
GMAT uses a native ASCII tracking data file format called a “GMAT Measurement Data File”, or
GMD file. This file format currently implements the following observation measurement types:
• DSN Sequential Ranging, TRK-2-34 data Type 7
• Derived Doppler using successive DSN Total Count Phase Doppler tracking measurements,
TRK-2-34 data Type 17
• Transmit frequency ramp records, TRK-2-34 data Type 9
Each GMD file consists of a series of space-delimited ASCII records. Details of the GMD file format
for each observation type are provided in the following sections. A single GMD file may contain
one or more of the record types described below, but ramp records must be in a separate file. For
further details on the TRK-2-34 data formats, please consult the TRK-2-34 DSN Tracking System Data
Archival Format, 820-013 Deep Space Network External Interface Specification.
DSN Sequential Range
DSN TRK-2-34 Sequential Ranging employs the DSNRange measurement type. DSNRange is a
round-trip range observation measured in range units. The GMD record format for DSNRange
tracking data is shown in the table below.
Field
Description
1
Observation receive time in TAIModJulian
2
Observation type name - DSN TRK-2-34 Type 7 Sequential Range = DSNRange
3
Observation type index number - 9004 = DSNRange (TRK-2-34)
4
Downlink Ground station pad ID
5
Spacecraft ID
6
Two-way (round-trip) range observation in Range Units
7
Uplink frequency band indicator - 0 = unknown, 1 = S-band, 2 = X-band, 3 = Kaband, 4 = Ku-band, 5 = L-band
8
Uplink frequency in Hz
9
Range modulo value in Range Units
The transmit frequency specified in the TRK-2-34 range data GMD file is only used if a frequency ramp table is not available. If a transmit frequency ramp record file is provided on the
TrackingFileSet.RampTable field, the transmit frequency will be determined from the ramp table
and the frequency specified in the range data GMD file will be ignored. A sample of GMD data
records for TRK-2-34 Sequential Range data is shown below.
629
Reference Guide
%
- 1 27236.157789352
27236.158240741
27236.158692130
27236.159143519
TrackingFileSet
- 2 DSNRange
DSNRange
DSNRange
DSNRange
3
9004
9004
9004
9004
4
45
45
45
45
5
59
59
59
59
- 6 +9.810325186004e+005
+5.813243487947e+005
+1.863046908683e+005
+8.450116485521e+005
7
1
1
1
1
- 8 +2.091414432000e+009
+2.091414432000e+009
+2.091414432000e+009
+2.091414432000e+009
- 9 +1.048576000000e+006
+1.048576000000e+006
+1.048576000000e+006
+1.048576000000e+006
DSN Total Count Phase
DSN TRK-2-34 Total Count Phase employs the Doppler measurement type. As shown below, the
GMAT Doppler measurement type, measured in Hz, is derived from successive Total Phase Count
(TCP) observations.
where
The GMD record format for Doppler tracking data is shown in the table below.
Field
Description
1
Observation receive time in TAIModJulian
2
Observation type name - DSN TRK-2-34 Type 17 Total Count Phase = Doppler
3
Observation type index number - 9006 = Doppler (TRK-2-34)
4
Downlink Ground station pad ID
5
Spacecraft ID
6
Uplink frequency band indicator - 0 = unknown, 1 = S-band, 2 = X-band, 3 = Kaband, 4 = Ku-band, 5 = L-band
7
Doppler count interval in seconds
8
Observation value - Doppler observable derived from Total Count Phase (TCP)
TRK-2-34 Type 17 measurements
A sample of GMD data records for TRK-2-34 Total Count Phase data is shown below.
%
- 1 27226.011944444
27226.012060185
27226.012175926
27226.012291667
- 2 Doppler
Doppler
Doppler
Doppler
3
9006
9006
9006
9006
4
15
15
15
15
5
6241
6241
6241
6241
6
1
1
1
1
7
10
10
10
10
- 8 -2.2445668331979342e+09
-2.2445668330920730e+09
-2.2445668329843016e+09
-2.2445668328729177e+09
Transmit Frequency Ramp Records
GMAT supports DSN tracking utilizing both constant and ramped transmit frequencies. If the transmit frequency is constant, GMAT will use the transmit frequency specified on the DSNRange measurement records for the computation of the range observation and a ramp table file is not required.
If the transmit frequency is ramped, the user must generate a GMD file of ramp records from
TRK-2-34 Type 9 raw data, and provide the GMD ramp table on the TrackingFileSet.RampTable
630
TrackingFileSet
Reference Guide
object field. If a ramp table is provided, GMAT ignores the frequency specified on the DSNRange
records and instead computes the transmit frequency from the ramp records.
The record format for ground-based range-rate tracking data is shown in the table below.
Field
Description
1
Observation receive time in TAIModJulian
2
Ground station pad ID
3
Spacecraft ID
4
Uplink frequency band indicator - 0 = unknown, 1 = S-band, 2 = X-band, 3 = Kaband, 4 = Ku-band, 5 = L-band
5
Ramp type - 0 = snap, 1 = start of new ramp, 2 = medial report, 3 = periodic report,
4 = end of ramps, 5 = ramping terminated by operator, 6 = invalid/unknown
6
Ramp frequency in Hz
7
Ramp rate in Hz/sec
A sample GMD ramp file is shown below.
%
- 1 27238.640625000
27238.654513889
27238.659664352
27238.668402778
27238.682291667
2
34
34
34
34
34
3
234
234
234
234
234
4
2
2
2
2
2
5
1
1
3
1
1
- 6 +7.186571173393e+09
+7.186571894665e+09
+7.186572153775e+09
+7.186572593389e+09
+7.186573264213e+09
- 7 +6.010599999990e-01
+5.822699999990e-01
+5.822699999990e-01
+5.590199999990e-01
+5.315100000000e-01
631
632
Reference Guide
Transmitter
Defines the electronics hardware, attached to a GroundStation resource, that transmits an RF signal.
Description
A ground station needs a Transmitter to transmit the RF signal to both user spacecraft and to
navigation spacecraft such as TDRS. A Transmitter is assigned on the AddHardware list of an
instance of a GroundStation.
See Also GroundStation, Antenna
Fields
Field
Description
Frequency
Transmit frequency
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
PrimaryAntenna
Real
Real >= 0
set
0
MHz
script
Antenna resource used by GroundStation resource to transmit a signal
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
Antenna Object
Any Antenna object
set
None
N/A
script
Remarks
Discussion of how Transmitter frequency is used
A transmitter will be attached to a GroundStation resource. As discussed in the RunSimulator
Help, for the case where a ramp table is not used, the transmit frequency is used directly to calculate
the DSN range and Doppler measurements. If a ramp table is specified on the relevant TrackingFileSet, the frequency profile specified in the ramp table is used and the transmitter frequency is
ignored.
Examples
Create and configure a Transmitter object
Create Antenna DSNAntenna;
Create Transmitter Transmitter1;
633
Reference Guide
Transmitter1.PrimaryAntenna = DSNAntenna;
Transmitter1.Frequency = 7186.3;
Create GroundStation DSN
DSN.AddHardware = {Transmitter1};
BeginMissionSequence;
634
Transmitter
Reference Guide
Transponder
Defines the electronics hardware, typically attached to a spacecraft, that receives and automatically
re-transmits an incoming signal.
Description
The spacecraft Transponder model is required for modeling DSN two way range and Doppler
data types. The Transponder object includes modeling of a retransmission delay due to the spacecraft transponder electronics. You can also specify a turn around ratio which is a multiplicative ratio
describing how the frequency of the retransmitted signal differs from the received frequency. The
incoming and outgoing frequencies are designed to be different so as to avoid RF interference between the signal transmitted by the ground station to the spacecraft and the return signal from the
spacecraft to the ground station.
See Also: GroundStation, Antenna
Fields
Field
Description
HardwareDelay
Transponder electronics delay between receiving time and transmitting
time at the transponder. It is applied for both simulation and estimation,
with or without ramp table use.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
PrimaryAntenna
Real
Real >= 0
set
0
seconds
script
Antenna resource used by the Transponder resource
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
Antenna Object
Any valid Antenna object
set
None
N/A
script
635
Reference Guide
Transponder
Field
Description
TurnAroundRatio
Transponder turn around ratio which is used in both simulation and estimation. For the DSN Doppler data type where an input ramp table is not
used, changing the transponder turn around ratio appreciably changes the
measurement. For all DSN data types, changing the turn around ratio affects the media correction calculations which will typically result in a small
change in the measurement. See the RunSimulator and RunEstimator
help for additional details.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
STRING_TYPE
A string in form of 'a/b' where a and b are real
numbers
set
'240/221'
N/A
script
Remarks
Turn around ratio affects media correction calculations
Suppose you are given a signal with multiple ‘n’ legs. In order to calculate the media corrections for
a given leg, we need to know the associated frequency for that leg. The turn-around ratio is used to
calculate the frequency for legs 2 through n. If media corrections are modeled, then, for both DSN
range and Doppler measurements, the value of the turn-around ratio, as set in the Transponder
resource, will have an effect on the measurements and thus both simulation and estimation processes
will be affected.
Independent of media corrections, how does the turn around ratio, as
set in the Transponder resource, affect DSN measurements?
Assume that media corrections are turned off so that we can ignore any, typically small, changes to
the DSN measurements caused by media corrections. We make the following observations.
1. The value of Transponder.TurnAroundRatio has no effect on DSN range measurements.
2. If a ramp table is provided, then the value of Transponder.TurnAroundRatio has no effect on
DSN Doppler measurements. In this case, the multiplicative turn around ratio used to calculate
the computed measurement is based upon the Uplink Band given in the ramp table. (240/221
for S-band and 880/749 for X band)
3. If a ramp table is not provided, then the value of Transponder.TurnAroundRatio has a proportional effect on DSN Doppler measurements. For example, if the turn around ratio is doubled, then so is the DSN Doppler measurement in Hz.
For additional discussion on how the Transponder.TurnAroundRatio field affects the DSN measurements, see the RunSimulator and RunEstimator help.
Custom turn-around ratios for DSN Doppler data
As mentioned above, the DSN Doppler (TRK-2-34 Type 17) data type observation value depends
upon the transponder turn-around ratio. As shown in the tables in the RunSimulator and RunEs636
Transponder
Reference Guide
timator help, for ramped Doppler data, GMAT only allows for the use of the standard S-band
(240/221) and X-band (880/749) turn-around ratios. For Doppler data where a ramp table is not
used, setting the Transponder turn-around ratio will correctly model the Doppler data. GMAT
cannot currently accommodate custom turn-around ratios for ramped Doppler data.
Examples
% Create and configure a Transponder object
Create Spacecraft Sat1;
Create Antenna HGA;
Create Transponder Transponder1;
Transponder1.PrimaryAntenna = HGA;
Transponder1.HardwareDelay
= 0.0;
Transponder1.TurnAroundRatio = '240/221';
Sat1.AddHardware = {HGA, Transponder1};
BeginMissionSequence;
637
638
Reference Guide
ChemicalThruster
A chemical thruster model
Description
The ChemicalThruster resource is a model of a chemical thruster which uses polynomials to model the thrust and specific impulse as a function of tank pressure and temperature. The ChemicalThruster model also allows you to specify properties such as a duty cycle and scale factor and to
connect a ChemicalThruster with a ChemicalTank. You can flexibly define the direction of the
thrust by specifying the thrust components in coordinate systems such as (locally defined) SpacecraftBody or LVLH, or by choosing any configured CoordinateSystem resource.
See Also: BeginFiniteBurn,ChemicalTank,FiniteBurn
Fields
The constants Ci below are used in the following equation to calculate thrust (in Newtons), FT, as
a function of pressure P (kPa) and temperature T (Celsius).
The constants Ki below are used in the following equation to calculate ISP (in seconds), Isp, as a
function of pressure P (kPa) and temperature T (Celsius).
Field
Description
Axes
Allows the user to define a spacecraft centered set of axes for the ChemicalThruster. This field cannot be modified in the Mission Sequence
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
Reference Array
VNB, LVLH, MJ2000Eq, SpacecraftBody
set
VNB
N/A
GUI, script
639
Reference Guide
ChemicalThruster
Field
Description
CoordinateSystem
Determines what coordinate system the orientation parameters, ThrustDirection1, ThrustDirection2, and ThrustDirection3 refer to. This
field cannot be modified in the Mission Sequence.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
C1
Thrust coefficient.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
C2
Real
Real Number
set, get
0
N
GUI, script
Thrust coefficient.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
640
Real
Real Number
set, get
0
N/kPa
GUI, script
Thrust coefficient.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
C4
Real
Real Number
set, get
10
N
GUI, script
Thrust coefficient.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
C3
Reference Array
Local, EarthMJ2000Eq, EarthMJ2000Ec,
EarthFixed, or any user defined system
set
Local
N/A
GUI, script
Real
Real Number
set, get
0
N/kPa
GUI, script
ChemicalThruster
Reference Guide
Field
Description
C5
Thrust coefficient.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
C6
Thrust coefficient.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
C7
Real
Real Number
set, get
0
None
GUI, script
Thrust coefficient.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
C9
Real
Real Number
set, get
0
N/kPaC7
GUI, script
Thrust coefficient.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
C8
Real
Real Number
set, get
0
N/kPa2
GUI, script
Real
Real Number
set, get
0
N/kPaC9
GUI, script
Thrust coefficient.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
Real
Real Number
set, get
0
None
GUI, script
641
Reference Guide
ChemicalThruster
Field
Description
C10
Thrust coefficient.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
C11
Thrust coefficient.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
C12
Real
Real Number
set, get
0
None
GUI, script
Thrust coefficient.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
642
Real
Real Number
set, get
0
N
GUI, script
Thrust coefficient.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
C14
Real
Real Number
set, get
0
None
GUI, script
Thrust coefficient.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
C13
Real
Real Number
set, get
0
N/kPaC11
GUI, script
Real
Real Number
set, get
0
1/kPa
GUI, script
ChemicalThruster
Reference Guide
Field
Description
C15
Thrust coefficient.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
C16
Thrust coefficient.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
DecrementMass
Boolean
true, false
set
false
N/A
GUI, script
Fraction of time that the thrusters are on during a maneuver. The thrust
applied to the spacecraft is scaled by this amount. Note that this scale
factor also affects mass flow rate.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
GravitationalAccel
Real
Real Number
set, get
0
1/kPa
GUI, script
Flag which determines if the FuelMass is to be decremented as it used.
This field cannot be modified in the Mission Sequence.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
DutyCycle
Real
Real Number
set, get
0
None
GUI, script
Real Number
0 <= Real <= 1
set, get
1
N/A
GUI, script
The gravitational acceleration.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
Real Number
Real > 0
set, get
9.81
m/s2
GUI, script
643
Reference Guide
ChemicalThruster
Field
Description
K1
ISP coefficient.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
K2
ISP coefficient.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
K3
Real
Real Number
set, get
0
s/kPa
GUI, script
ISP coefficient.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
644
Real
Real Number
set, get
0
s
GUI, script
ISP coefficient.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
K5
Real
Real Number
set, get
0
s/kPa
GUI, script
ISP coefficient.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
K4
Real
Real Number
set, get
300
s
GUI, script
Real
Real Number
set, get
0
s/kPa2
GUI, script
ChemicalThruster
Reference Guide
Field
Description
K6
ISP coefficient.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
K7
ISP coefficient.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
K8
Real
Real Number
set, get
0
s/kPaC9
GUI, script
ISP coefficient.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
K10
Real
Real Number
set, get
0
None
GUI, script
ISP coefficient.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
K9
Real
Real Number
set, get
0
s/kPaC7
GUI, script
Real
Real Number
set, get
0
None
GUI, script
ISP coefficient.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
Real
Real Number
set, get
0
s/kPaC11
GUI, script
645
Reference Guide
ChemicalThruster
Field
Description
K11
ISP coefficient.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
K12
ISP coefficient.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
K13
Real
Real Number
set, get
0
1/kPa
GUI, script
ISP coefficient.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
646
Real
Real Number
set, get
0
None
GUI, script
ISP coefficient.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
K15
Real
Real Number
set, get
0
s
GUI, script
ISP coefficient.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
K14
Real
Real Number
set, get
0
None
GUI, script
Real
Real Number
set, get
0
None
GUI, script
ChemicalThruster
Reference Guide
Field
Description
K16
ISP coefficient.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
MixRatio
The mixture ratio employed to draw fuel from multiple tanks. For example,
if there are two tanks and MixRatio is set to [2 1], then twice as much fuel
will be drawn from tank one as from tank 2 in the Tank list. Note, if a
MixRatio is not supplied, fuel is drawn from tanks in equal amounts, (the
MixRatio is set to a vector of ones the same length as the Tank list).
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
Origin
Real
Real Number
set, get
0
1/kPa
GUI, script
Array
Array of real numbers with same length as number of tanks in the Tank array
set
[1]
N/A
GUI, script
This field, used in conjunction with the Axes field, allows the user to define
a spacecraft centered set of axes for the ChemicalThruster. Origin has
no affect when a Local coordinate system is used and the Axes are set
to MJ2000Eq or SpacecraftBody. This field cannot be modified in the
Mission Sequence.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
Reference Array
Sun, Mercury, Venus, Earth, Luna,
Mars,Jupiter, Saturn, Uranus, Neptune, Pluto
set
Earth
N/A
GUI, script
647
Reference Guide
ChemicalThruster
Field
Description
Tanks
A list of ChemicalTank(s) from which the thruster draws propellant
from. In the script, an empty list, e.g., Thruster1.Tank = {}, is NOT
allowed. Via the script, if you wish to indicate that no tank is associated
with a thruster, do not include commands such as Thruster1.Tank
= ... in your script. This field cannot be modified in the Mission Sequence.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
ThrustDirection1
X component of the spacecraft thrust vector direction.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
ThrustDirection2
Real
Real Number
set, get
1
N/A
GUI, script
Z component of the spacecraft thrust vector direction.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
648
Real
Real Number
set, get
1
N/A
GUI, script
Y component of the spacecraft thrust vector direction.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
ThrustDirection3
Reference Array
User defined list of tank(s).
set
N/A
N/A
GUI, script
Real
Real Number
set, get
0
N/A
GUI, script
ChemicalThruster
Reference Guide
Field
Description
ThrustScaleFactor
ThrustScaleFactor is a scale factor that is multiplied by the thrust vector,
for a given thruster, before the thrust vector is added into the total acceleration. Note that the value of this scale factor does not affect the mass
flow rate.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
Real Number
Real >= 0
set, get
1
N/A
GUI, script
Interactions
Command or Resource
Description
BeginFiniteBurn/EndFiniteBurn command
Use these commands, which require a Spacecraft and a FiniteBurn name
as input, to implement a finite burn.
ChemicalTank
source
re- This resource contains the fuel used to power the ChemicalThruster specified by the FiniteBurn resource.
FiniteBurn
source
re- When using the BeginFiniteBurn/EndFiniteBurn commands, you must
specify which FiniteBurn resource to implement. The FiniteBurn resource
specifies which ChemicalThruster(s) to use for the finite burn.
Spacecraft resource When using the BeginFiniteBurn/EndFiniteBurn commands, you must
specify which Spacecraft to apply the finite burn to.
Propagate
mand
com- In order to implement a non-zero finite burn, a Propagate statement must
occurr within the BeginFiniteBurn and EndFiniteBurn statements.
GUI
The ChemicalThruster dialog box allows you to specify properties of a ChemicalThruster including the Coordinate System of the thrust acceleration direction vector, the thrust magnitude
and Isp coefficients, and choice of ChemicalTank. The layout of the ChemicalThruster dialog
box is shown below.
649
Reference Guide
ChemicalThruster
When configuring the Coordinate System field, you can choose between existing coordinate systems or use locally defined coordinate systems. The Axes field is only active if Coordinate System
is set to Local. The Origin field is only active if Coordinate System is set to Local and Axes is
set to either VNB or LVLH.
As shown below, if Decrement Mass is checked, then you can input the gravitational acceleration
value used to calculate fuel use. The value of the gravitational acceleration input here only affects
fuel use and does not affect the force model.
650
ChemicalThruster
Reference Guide
Selecting the Edit Thruster Coef. button brings up the following dialog box where you may input
the coefficients for the ChemicalThruster polynomial.
651
Reference Guide
ChemicalThruster
Similarly, clicking the Edit Impulse Coef. button brings up the following dialog box where you may
input the coefficients for the specific impulse (ISP) polynomial.
652
ChemicalThruster
Reference Guide
Remarks
Use of ChemicalThruster Resource in Conjunction With Maneuvers
A ChemicalThruster resource is used only in association with finite maneuvers. To implement
a finite maneuver, you must first create both a ChemicalTank and a FiniteBurn resource. You
must also associate a ChemicalTank with the ChemicalThruster resource and you must associate
a ChemicalThruster with the FiniteBurn resource. The finite maneuver is implemented using
the BeginFiniteBurn/EndFiniteBurn commands. See the BeginFiniteBurn/EndFiniteBurn
command documentation for worked examples on how the ChemicalThruster resource is used in
conjunction with finite maneuvers.
Thrust and ISP Calculation
Unscaled thrust, FT, and Isp, as a function of Pressure, in kPa, and Temperature, in degrees Celsius,
are calculated using the following polynomials.
653
Reference Guide
ChemicalThruster
The thrust, T, output in Newtons, is scaled by the Duty Cycle and Thrust Scale Factor. The
thrust acceleration direction vector (the direction of the actual acceleration not the thruster nozzle)
is given by ThrustDirection1-3 and is applied in the input Coordinate System. The Isp is output
in seconds.
The mass flow rate and the thrust equations are shown below where FT and Isp are defined above,
fd is the duty cycle, fs is the thrust scale factor, RiT is the rotation matrix from the thrust coordinate
system to the inertial system, and Td is the unitized thrust direction.
Local Coordinate Systems
Here, a Local coordinate system is defined as one that we configure "locally" using the ChemicalThruster 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 thrust
acceleration direction vector, ThrustDirection1-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 completes the right-handed set.
Similarly, Local Vertical Local Horizontal or LVLH is also a non-inertial coordinate system based
upon the motion of the spacecraft with respect to the Origin sub-field. Again, if we choose Earth as
the origin, then the X-axis of this coordinate system is the position of the spacecraft with respect to
the Earth, the Z-axis is the instantaneous orbit normal (with respect to the Earth) of the spacecraft,
and the Y-axis completes the right-handed set.
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 attitude system of 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.
Caution When Setting the ChemicalTank Temperature and Reference
Temperature
Note that both the thrust and ISP polynomials have terms that involve the ratio, (Temperature /
Reference Temperature). For GMAT, this temperature ratio is calculated in Celsius units, and thus,
there is a discontinuity when the Reference Temperature is equal to zero. For this reason, GMAT
requires that the absolute value of the input Reference Temperature is greater than 0.01.
654
ChemicalThruster
Reference Guide
Note also that the form of the Thrust and ISP polynomial has some behavior, when the Reference
Temperature is near 0 degrees Centigrade, that you need to be aware of. Because of the previously
mentioned discontinuity, the polynomials do not vary smoothly when the Reference Temperature
is near zero. For example, consider the two Reference Temperatures, -0.011 and + 0.011 degrees
Centigrade. These two temperatures are close to each other in value and one might expect that they
have roughly similar thrust and ISP values. This may not be the case, depending upon your choice of
thrust/ISP coefficients, since the temperature ratios associated with the two Reference Temperatures
have the same magnitude but different signs. You may choose to set the input Reference Temperature
equal to the input Temperature, thus eliminating any dependence of thrust and ISP with temperature
when using the currently implemented ChemicalTank model based upon Boyle’s Law where the
fuel Temperature does not change as fuel is depleted.
Examples
Create a default ChemicalTank and a ChemicalThruster that allows for fuel depletion, assign
the ChemicalThruster the default ChemicalTank, and attach both the ChemicalThruster and
ChemicalTank to a Spacecraft.
% Create the ChemicalTank Resource
Create ChemicalTank 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 a ChemicalThruster, that allows fuel depletion, and assign it a Chemi
Create ChemicalThruster Thruster1
Thruster1.CoordinateSystem = Local
Thruster1.Origin = Earth
Thruster1.Axes = VNB
Thruster1.ThrustDirection1 = 1
Thruster1.ThrustDirection2 = 0
Thruster1.ThrustDirection3 = 0
Thruster1.DutyCycle = 1
Thruster1.ThrustScaleFactor = 1
Thruster1.DecrementMass = true
Thruster1.Tank = {FuelTank1}
Thruster1.GravitationalAccel = 9.810000000000001
Thruster1.C1 = 10
Thruster1.C2 = 0
Thruster1.C3 = 0
Thruster1.C4 = 0
Thruster1.C5 = 0
Thruster1.C6 = 0
Thruster1.C7 = 0
655
Reference Guide
ChemicalThruster
Thruster1.C8 = 0
Thruster1.C9 = 0
Thruster1.C10 = 0
Thruster1.C11 = 0
Thruster1.C12 = 0
Thruster1.C13 = 0
Thruster1.C14 = 0
Thruster1.C15 = 0
Thruster1.C16 = 0
Thruster1.K1 = 300
Thruster1.K2 = 0
Thruster1.K3 = 0
Thruster1.K4 = 0
Thruster1.K5 = 0
Thruster1.K6 = 0
Thruster1.K7 = 0
Thruster1.K8 = 0
Thruster1.K9 = 0
Thruster1.K10 = 0
Thruster1.K11 = 0
Thruster1.K12 = 0
Thruster1.K13 = 0
Thruster1.K14 = 0
Thruster1.K15 = 0
Thruster1.K16 = 0
% Add the ChemicalThruster and the ChemicalTank to a Spacecraft
Create Spacecraft DefaultSC
DefaultSC.Tanks = {FuelTank1}
DefaultSC.Thrusters = {Thruster1}
BeginMissionSequence
Create two ChemicalTanks (called aTank1 and aTank2) and a ChemicalThruster, attach both
the ChemicalThruster and ChemicalTanks to a Spacecraft, and configure the thruster to draw
four times as much fuel from aTank1 than aTank2.
% Create the ChemicalTank Resource
Create Spacecraft aSat
aSat.Tanks = {aTank1,aTank2}
aSat.Thrusters = {aThruster}
% Create two tanks
Create ChemicalTank aTank1 aTank2
% Configure thruster to draw four times as much fuel
% from aTank1 than aTank2
Create ChemicalThruster aThruster
aThruster.Tank = {aTank1,aTank2}
656
ChemicalThruster
Reference Guide
aThruster.MixRatio = [4 1]
BeginMissionSequence
657
658
Reference Guide
Variable
A user-defined numeric variable
Description
The Variable resource is used to store a single numeric value for use by commands in the Mission
Sequence. It can be used in place of a literal numeric value in most commands. Variable resources
are initialized to zero on creation, and can be assigned 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.
See Also: Array, String
Fields
The Variable resource has no fields; instead, the resource itself is set to the desired value.
Field
Description
value
The value of the variable.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
Real number
-∞ < value < ∞
set, get
0.0
N/A
GUI, script
GUI
The GMAT GUI lets you create multiple Variable resources at once without leaving the window.
To create a Variable:
1. In the Variable Name box, type the desired name of the variable.
2. In the Variable Value box, type the initial value of the variable. This is required and must be a
literal numeric value.
659
Reference Guide
Variable
3. Click the => button to create the variable and add it to the list on the right.
You can create multiple Variable resources this way. To edit an existing variable in this window, click
it in the list on the right and edit the value. You must click the => button again to save your changes.
You can also double-click an existing variable in the resources tree in the main GMAT window. This
opens the Variable properties box above that allows you to edit the value of that individual variable.
Remarks
GMAT Variable resources store a single numeric value. Internally, the value is stored as a double-precision real number, regardless of whether or not a fractional portion is present.
Examples
Creating a variable and assigning it a literal value:
Create ReportFile aReport
Create Variable aVar
aVar = 12
BeginMissionSequence
Report aReport aVar
Using variables in Mission Sequence commands:
Create Spacecraft aSat
Create ForceModel anFM
Create ReportFile aReport
Create Propagator aProp
aProp.FM = anFM
Create Variable i step totalDuration nSteps
BeginMissionSequence
660
Variable
Reference Guide
step = 60
totalDuration = 24*60^2
% one day
nSteps = totalDuration / step
% Report Keplerian elements every 60 seconds for one day
For i=1:nSteps
Propagate aProp(aSat) {aSat.ElapsedSecs = step}
Report aReport aSat.TAIModJulian aSat.SMA aSat.ECC aSat.INC ...
aSat.RAAN aSat.AOP aSat.TA
EndFor
661
662
Reference Guide
VF13ad
The Sequential Quadratic Programming (SQP) optimizer, VF13ad
Description
The VF13ad optimizer is a SQP-based Nonlinear Programming solver available in the Harwell
Subroutine Library. VF13ad performs nonlinear constrained optimization and supports both linear
and nonlinear constraints. To use this solver, you must configure the solver options including convergence criteria, maximum iterations, and gradient computation method. In the mission sequence,
you implement an optimizer such as VF13ad 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: FminconOptimizer,Optimize,Vary, NonlinearConstraint, Minimize
Fields
Field
Description
FeasibilityTolerance
Specifies the accuracy to which you want constraints to be satisfied.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
MaximumIterations
Specifies the maximum allowable number of nominal passes through the
Solver Control Sequence.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
ReportFile
Real
Real > 0
set
1e-3
None
GUI, script
Integer
Integer > 0
set
200
None
GUI, script
Contains the path and file name of the report file.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
String
Any user-defined file name
set
VF13adVF13ad1.data
None
GUI, script
663
Reference Guide
VF13ad
Field
Description
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
Allowed Values
Access
Default Value
Units
Interfaces
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
Allowed Values
Access
Default Value
Units
Interfaces
Tolerance
Real
Real > 0
set
1e-5
None
GUI, script
Allows you to choose whether or not to use central differencing for numerically determining the derivative. For the default, 'false' value of this
field, forward differencing is used to calculate the derivative.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
664
Boolean
true, false
set
true
None
GUI, script
Specifies the measure the optimizer will use to determine when an optimal
solution has been found based on the value of the goal set in a Minimize
command.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
UseCentralDifferences
String
Normal, Concise, Verbose, Debug
set
Normal
None
GUI, script
Boolean
true, false
set
false
None
GUI, script
VF13ad
Reference Guide
GUI
The VF13ad dialog box allows you to specify properties of a VF13ad such as as maximum iterations,
cost function tolerance, feasibility tolerance, choice of reporting options, and choice of whether or
not to use the central difference derivative method.
To create a VF13ad 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 VF13ad. This will
create a new VF13ad resource, VF13ad1. Double-click on VF13ad1 to bring up the VF13ad dialog
box shown below.
Remarks
VF13ad Optimizer Availability
This optimizer is not included as part of the nominal GMAT installation and is only available if you
have created and installed the VF13ad plug-in.
Resource and Command Interactions
The VF13ad 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 VF13ad resource named VF13ad1.
Create VF13ad VF13ad1
VF13ad1.ShowProgress = true
VF13ad1.ReportStyle = Normal
VF13ad1.ReportFile = 'VF13adVF13ad1.data'
665
Reference Guide
VF13ad
VF13ad1.MaximumIterations = 200
VF13ad1.Tolerance = 1e-005
VF13ad1.UseCentralDifferences = false
VF13ad1.FeasibilityTolerance = 1e-003
For an example of how a VF13ad resource can be used within an Optimization sequence, see the
Optimize command examples.
666
Reference Guide
XYPlot
Plots data onto the X and Y axes of a graph
Description
The XYPlot resource allows you to plot data onto the X and Y axis of the graph. You can choose
to plot any number of parameters as a function of a single independent variable. GMAT allows you
to plot user-defined variables, array elements, or spacecraft parameters. You can create multiple XYPlots by using either the GUI or script interface of GMAT. GMAT also provides the option of when
to plot and stop plotting data to a XYPlot through the Toggle On/Off command. See the Remarks
section below for detailed discussion of the interaction between an XYPlot resource and the Toggle
command. GMAT’s Spacecraft and XYPlot resources also interact with each other throughout the
entire mission duration. Discussion of the interaction between Spacecraft and XYPlot resources
can also be found in the Remarks section.
See Also: Toggle, Spacecraft
Fields
Field
Description
Maximized
Allows the user to maximize the XYPlot window. This field cannot be
modified in the Mission Sequence.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
UpperLeft
Boolean
true,false
set
false
N/A
script
Allows the user to pan the XYPlot display window in any direction. First
value in [0 0] matrix helps to pan the XYPlot window horizontally and
second value helps to pan the window vertically. This field cannot be modified in the Mission Sequence.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
Real array
Any Real number
set
[0 0]
N/A
script
667
Reference Guide
XYPlot
Field
Description
RelativeZOrder
Allows the user to select which XYPlot window to display first on the
screen. The XYPlot with lowest RelativeZOrder value will be displayed
last while XYPlot with highest RelativeZOrder value will be displayed
first. This field cannot be modified in the Mission Sequence.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
ShowGrid
When the ShowGrid field is set to True, then a grid is drawn on an xyplot. When the ShowGrid field is set to False, then a grid is not drawn.
This field cannot be modified in the Mission Sequence.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
ShowPlot
Boolean
True,False
set
True
N/A
GUI, script
Allows the user to control the display size of XYPlot window. First value in
[0 0] matrix controls horizonal size and second value controls vertical size
of XYPlot display window. This field cannot be modified in the Mission
Sequence.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
668
Boolean
True,False
set
True
N/A
GUI, script
Allows the user to turn off a plot for a particular run, without deleting the
XYPlot resource, 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
Allowed Values
Access
Default Value
Units
Interfaces
Size
Integer
Integer ≥ 0
set
0
N/A
script
Real array
Any Real number
set
[00]
N/A
script
XYPlot
Reference Guide
Field
Description
SolverIterations
This field determines whether or not data associated with perturbed trajectories during a solver (Targeter, Optimize) sequence is displayed in
the XYPlot. When SolverIterations is set to All, all perturbations/iterations are plotted in the XYPlot. When SolverIterations is set to Current, only the current solution or perturbation is plotted in XYPlot. When
SolverIterations is set to None, only the final nominal run is plotted on
the XYPlot.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
XVariable
Allows the user to define the independent variable for an XYPlot. Only
one variable can be defined as an independent variable. For example, the
line MyXYPlot.XVariable = DefaultSC.A1ModJulian sets the
independent variable to be the epoch of DefaultSC in the A1 time system
and modified Julian format. This field cannot be modified in the Mission
Sequence.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
YVariable
Enumeration
All, Current, None
set
Current
N/A
GUI, script
Resource reference
Variable, Array, array element, Spacecraft parameter that evaluates to a real number
get, set
DefaultSC.A1ModJulian
N/A
GUI, script
Allows the user to add dependent variables to an xy-plot.
All dependent variables are plotted on the y-axis vs the independent variable defined by XVariable field. The dependent
variable(s) should always be included in curly braces. For example,
MyXYPlot.YVariables = {DefaultSC.EarthMJ2000Eq.Y,
DefaultSC.EarthMJ2000Eq.Z}. This field cannot be modified in the
Mission Sequence.
Data Type
Allowed Values
Access
Default Value
Units
Interfaces
Reference array
Any user variable, array element, or spacecraft parameter that evaluates to a real number
get, set
DefaultSC.EarthMJ2000Eq.X
N/A
GUI, script
GUI
The figure below shows the default settings for the XYPlot resource:
669
Reference Guide
XYPlot
Remarks
Behavior when using XYPlot Resource & Toggle Command
The XYPlot resource plots data onto the X and Y axis of the graph at each propagation step of the
entire mission duration. If you want to report data to an XYPlot at specific points in your mission,
then a Toggle On/Off command can be inserted into the mission sequence to control when the
XYPlot is to plot data. When Toggle Off command is issued for a XYPlot, no data is plotted onto
the X and Y axis of the graph until a Toggle On command is issued. Similarly when a Toggle On
command is used, data is plotted onto the X and Y axis 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 commands
while using the XYPlot resource. Spacecraft’s position magnitude and semi-major-axis are plotted
as a function of time.
Create Spacecraft aSat
Create Propagator aProp
Create XYPlot aXYPlot
aXYPlot.XVariable = aSat.ElapsedDays
aXYPlot.YVariables = {aSat.Earth.RMAG, aSat.Earth.SMA}
BeginMissionSequence
Toggle aXYPlot Off
Propagate aProp(aSat) {aSat.ElapsedDays = 2}
Toggle aXYPlot On
670
XYPlot
Reference Guide
Propagate aProp(aSat) {aSat.ElapsedDays = 4}
Behavior when using XYPlot & Spacecraft resources
Spacecraft resource contains information about spacecraft’s orbit, its attitude, physical parameters
(such as mass and drag coefficient) and any attached hardware, including thrusters and fuel tanks.
Spacecraft resource interacts with XYPlot throughout the entire mission duration. The data retrieved from the spacecraft is what gets plotted onto the X and Y axis of the graph at each propagation step of the entire mission duration.
Behavior When Specifying Empty Brackets in XYPlot's YVariables Field
When using XYPlot.YVariables field, GMAT does not allow brackets to be left empty. The brackets
must always be populated with values that you wish to plot against a variable in XVariable field.
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 for YVariables field cannot be left empty.
Create Spacecraft aSat
Create Propagator aProp
Create XYPlot aXYPlot
aXYPlot.XVariable = aSat.ElapsedDays
aXYPlot.YVariables = {}
BeginMissionSequence
Propagate aProp(aSat) {aSat.ElapsedDays = 2}
Behavior when Reporting 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 an XYPlot resource supports
three options which are described in the table below:
SolverIterations
options
Description
Current
Shows only current iteration/perturbation in an iterative process and plots current iteration to a plot.
All
Shows all iterations/perturbations in an iterative process and plots all iterations/perturbations to a plot.
None
Shows only the final solution after the end of an iterative process and plots only
that final solution to the plot.
Examples
Propagate an orbit and plot the spacecraft’s altitude as a function of time at every integrator step:
Create Spacecraft aSat
Create Propagator aProp
671
Reference Guide
XYPlot
Create XYPlot aXYPlot
aXYPlot.XVariable = aSat.ElapsedSecs
aXYPlot.YVariables = {aSat.Earth.Altitude}
BeginMissionSequence
Propagate aProp(aSat) {aSat.ElapsedDays = 4}
Plotting data 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 XYPlot aXYPlot
aXYPlot.SolverIterations = All
aXYPlot.XVariable = aSat.ElapsedDays
aXYPlot.YVariables = {aSat.Earth.RMAG}
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
672
Reference Guide
Commands
Table of Contents
Achieve .........................................................................................................................
Assignment (=) ..............................................................................................................
BeginFiniteBurn .............................................................................................................
BeginMissionSequence ....................................................................................................
BeginScript ....................................................................................................................
CallGmatFunction ..........................................................................................................
CallMatlabFunction ........................................................................................................
CallPythonFunction ........................................................................................................
ClearPlot .......................................................................................................................
EndFiniteBurn ...............................................................................................................
FindEvents ....................................................................................................................
For ................................................................................................................................
GetEphemStates() ..........................................................................................................
Global ...........................................................................................................................
If ..................................................................................................................................
Maneuver ......................................................................................................................
MarkPoint .....................................................................................................................
Minimize .......................................................................................................................
NonlinearConstraint .......................................................................................................
Optimize .......................................................................................................................
PenUpPenDown ............................................................................................................
Propagate ......................................................................................................................
Report ...........................................................................................................................
RunEstimator .................................................................................................................
RunSimulator .................................................................................................................
Set ................................................................................................................................
Stop ..............................................................................................................................
Target ...........................................................................................................................
Toggle ...........................................................................................................................
Vary ..............................................................................................................................
While ............................................................................................................................
Write .............................................................................................................................
675
677
687
693
695
697
703
707
711
715
717
723
727
733
739
743
747
751
755
759
765
769
781
785
787
791
793
795
803
807
815
819
673
674
Reference Guide
Achieve
Specify a goal for a Target sequence
Script Syntax
Achieve SolverName (Goal = Arg1, [{Tolerance = Arg2}])
Description
The Achieve command is used in conjunction with the Target command as part of the Target
sequence. The purpose of the Achieve command is to define a goal for the targeter (currently,
the differential corrector is the only targeter available within a Target sequence) to achieve. To
configure the Achieve command, you specify the goal object, its corresponding desired value, and
an optional tolerance so the differential corrector can find a solution. The Achieve command must
be accompanied and preceded by a Vary command in order to assist in the targeting process.
See Also: DifferentialCorrector, Target, Vary
Options
Option
Description
Arg1
Specifies the desired value for the Goal after the DifferentialCorrector has converged.
Accepted Data Types
Allowed Values
Default Value
Required
Interfaces
Arg2
Convergence tolerance for how close Goal equals Arg1
Accepted Data Types
Allowed Values
Default Value
Required
Interfaces
Goal
Array, ArrayElement, Variable, String
Real Number, Array element, or Variable
42165
yes
GUI, script
Real Number, Array element, Variable, or any userdefined parameter > 0
Real Number, Array element, Variable, or any userdefined parameter > 0
0.1
no
GUI, script
Allows you to select any single element user defined parameter, except a number,
as a targeter goal.
Accepted Data Types
Allowed Values
Default Value
Required
Interfaces
Object parameter, ArrayElement, Variable
Spacecraft parameter, Array element, Variable,
or any other single element user defined parameter,
excluding numbers
DefaultSC.Earth.RMAG
yes
GUI, script
675
Reference Guide
Achieve
Option
Description
SolverName Specifies the DifferentialCorrector being used in the Target sequence
Accepted Data Types
Allowed Values
Default Value
Required
Interfaces
String
Any user defined DifferentialCorrector
DefaultDC
yes
GUI, script
GUI
You use an Achieve command, which is only valid within a Target sequence, to define your desired
goal. More than one Achieve command may be used within a Target command sequence. The
Achieve command dialog box, which allows you to specify the targeter, goal object, goal value, and
convergence tolerance, is shown below.
Remarks
Command Interactions
A Target sequence must contain at least one Vary and one Achieve command.
Target
command
An Achieve command only occurs within a Target sequence
Vary com- Associated with any Achieve command is at least one Vary command. The Vary
mand
command identifies the control variable used by the targeter. The goal specified by
the Achieve command is obtained by varying the control variables.
Examples
As mentioned above, an Achieve command only occurs within a Target sequence. See the Target
command help for examples showing the use of the Achieve command.
676
Reference Guide
Assignment (=)
Set a variable or resource field to a value, possibly using mathematical expressions
Script Syntax
settable_item = expression
Description
The assignment command (in the GUI, the Equation command) allows you to set a resource field or
parameter to a value, possibly using mathematical expressions. GMAT uses the assignment operator
('=') to indicate an assignment command. The assignment operator uses the following syntax, where
LHS denotes the left-hand side of the operator, and RHS denotes the right-hand side of the operator:
LHS = RHS
In this expression, the left-hand side (LHS) is being set to the value of the right-hand side (RHS).
The syntax of the LHS and RHS expressions vary, but both must evaluate to compatible data types
for the command to succeed.
Left-hand side
The left-hand side of the assignment command must be a single item of any of the following types:
•
•
•
•
allowed resource (e.g. Spacecraft, Variable, Array)
resource field for allowed resources (e.g. Spacecraft.Epoch, Spacecraft.DateFormat)
settable resource parameter (e.g. Spacecraft.X, ReportFile.Precision)
Array or Array element
See the documentation for a particular resource to determine which fields and parameters can be set.
Right-hand side
The right-hand side of the assignment command can consist of any of the following:
•
•
•
•
•
•
literal value
resource (e.g. Spacecraft, Variable, Array)
resource field (e.g. Spacecraft.Epoch, Spacecraft.DateFormat)
resource parameter (e.g. Spacecraft.X, ChemicalThruster.K1)
Array or Array element
mathematical expression (see below)
MATLAB function calls are considered distinct from the assignment command. See the reference
pages for more information.
677
Reference Guide
Assignment (=)
GUI
The assignment command in the script language corresponds to the Equation command in the
GUI. The Equation properties box allows you to input both sides of the expression into free-form
text boxes. The default values on each side are “Not_Set”; these are placeholders only, and are not
valid during the mission run. You can type into each box the same syntax described above for the
script language. When you click OK or Apply, GMAT validates each side of the expression and
provides feedback for any warnings or errors.
Remarks
Data type compatibility
In general, the data types of the left-hand side and the right-hand side must match after all expressions are evaluated. This means that a Spacecraft resource can only be set to another Spacecraft
resource, numeric parameters can only be set to numeric values, and String resources can only be
set to string values. Additionally, the dimension of Array instances must match for the command
to succeed. For numeric quantities, the assignment command does not distinguish between integers
and floating-point values.
Parameters
Parameters can be used on either side of an assignment command, but there may be certain restrictions.
On the right-hand side of the command, any parameter can be used. If a parameter accepts a
dependency (such as Spacecraft.CoordinateSystem.X) and the dependency is omitted, a default dependency value will be used. For coordinate-system-dependent parameters, the default is
EarthMJ2000Eq. For central-body-dependent parameters, the default is Earth.
On the left-hand side, only settable (writable) parameters can be used. Furthermore, no dependency
can be specified, except in the special case that the dependencies on both sides of the assignment
command are equivalent. On the left-hand side, the default values of omitted dependencies are automatically taken to be the current values of the CoordinateSystem field of the referenced Spacecraft and its origin.
These examples show valid and invalid usage of parameters:
Create Spacecraft aSat1 aSat2
aSat2.CoordinateSystem = 'EarthFixed'
Create Variable x
678
Reference Guide
Assignment (=)
BeginMissionSequence
x = aSat1.EarthFixed.X
x = aSat1.EarthMJ2000Eq.X
x = aSat1.X
% Valid: Parameter with dependency on RHS
% Valid: This and next statement are equiv.
% Valid: Default dep. value is EarthMJ2000Eq.
x = aSat1.Mars.Altitude
x = aSat1.Earth.Altitude
x = aSat1.Altitude
% Valid: Parameter with dependency on RHS
% Valid: This and next statement are equiv.
% Valid: Default dependency value is Earth.
aSat2.X = 1e5
aSat2.EarthMJ2000Eq.X = 1e5
aSat2.EarthFixed.X = 1e5
% Valid: Default parameter value is EarthFixed.
% INVALID: Dependencies not allowed on LHS.
% Valid: Special case because value = default.
aSat2.EarthMJ2000Eq.X = aSat1.EarthFixed.X
% INVALID: Dependency on LHS
aSat2.EarthMJ2000Eq.X = aSat1.EarthMJ2000Eq.X % INVALID: Dependency on LHS
aSat2.EarthFixed.X = aSat1.EarthFixed.X
% Valid: Special case
% DANGEROUS! Valid, but sets EarthMJ2000Eq RHS values to EarthFixed LHS param.
aSat2.X = aSat1.EarthMJ2000Eq.X
% DANGEROUS! RHS default is EarthMJ2000Eq, LHS default is current setting on
% aSat2 (EarthFixed in this case).
aSat2.X = aSat1.X
Mathematical Expressions
The assignment command supports the use of inline mathematical expressions on the right-hand
side of the command. These expressions follow the general syntax rules of MATLAB expressions,
and can use a variety of operators and built-in functions.
Parsing
Mathematical expressions are recognized by the presence of any of the operators or built-in functions described below. Before execution, all white space (e.g. spaces and tabs) is removed from the
expression.
Data Types
Mathematical expressions operate on numeric values (integers or floating-point numbers). This includes the following:
•
•
•
•
•
•
literal values
numeric resources (Variable, Array)
gettable resource parameters (e.g. Spacecraft.X, ChemicalThruster.K1)
Array elements
calculation parameters (e.g. Spacecraft.OrbitPeriod)
nested mathematical expressions
Several of GMAT’s operators and functions are vectorized, so they operate on full Array resources
as well as scalar numeric values.
679
Reference Guide
Assignment (=)
Operators
Vectorized +
operators
-
*
'
Scalar oper- /
ators
^
Addition or unary plus. X+Y adds X and Y. X and Y must have the same dimensions
unless either is a scalar.
Subtraction or unary minus. -X is the negative of X, where X can be any size. XY subtracts Y from X. X and Y must have the same dimensions unless either is
a scalar.
Multiplication. X*Y is the product of X and Y. If both X and Y are scalars, this
is the simple algebraic product. If X is a matrix or vector and Y is a scalar, all
elements of X are multiplied by Y (and vice versa). If both X and Y are non-scalar,
X*Y performs matrix multiplication and the number of columns in X must equal
the number of rows in Y.
Transpose. X' is the transpose of X. If X is a scalar, X' is equal to X.
Division. X/Y divides X by Y. If both X and Y are scalars, this is the simple algebraic quotient. If X is a matrix or vector, each element is divided by Y. Y must
be a non-zero scalar quantity.
Power. X^Y raises X to the Y power. X and Y must be scalar quantities. A special
case is X^(-1), which when applied to a square matrix X, returns the inverse of X.
When multiple expressions are combined, GMAT uses the following order of operations. Operations
begin with those operators at the top of the list and and continue downwards. Within each level,
operations proceed left-to-right.
1.
2.
3.
4.
5.
parentheses ()
transpose ('), power (^)
unary plus (+), unary minus (-)
multiplication (*), division (/)
addition (+), subtraction (-)
Built-in Functions
GMAT supports the following built-in functions in mathematical expressions. Supported functions
include common scalar functions, meaning they accept a single value only, such as sin and cos, matrix
functions that operate on an entire matrix or vector, and string functions.
680
Reference Guide
Assignment (=)
Scalar Math sin
Functions
cos
tan
asin
acos
atan
atan2
log
log10
exp
DegToRad
RadToDeg
abs
sqrt
Sine. In Y = sin(X), Y is the sine of the angle X. X must be in radians.
Y will be in the range [-1, 1].
Cosine. In Y = cos(X), Y is the cosine of the angle X. X must be in
radians. Y will be in the range [-1, 1].
Tangent. In Y = tan(X), Y is the tangent of the angle X. X must be
in radians. The tangent function is undefined at angles that normalize
to p/2 or -p/2.
Arcsine. In Y = asin(X), Y is the arcsine of X. X must be in the
range [-1, 1], and Y will be in the range [-p/2, p/2].
Arccosine. In Y = acos(X), Y is the arccosine of X. X must be in
the range [-1, 1], and Y will be in the range [0, p].
Arctangent. In Y = atan(X), Y is the arctangent of X. Y will be in
the range (-p/2, p/2).
Four-quadrant arctangent. In A = atan2(Y, X), A is the arctangent
of Y/X. A will be in the range (-p, p]. atan2(Y, X) is equivalent to
atan(Y/X) except for the expanded range.
Natural logarithm. In Y = log(X), Y is the natural logarithm of X.
X must be non-zero positive.
Common logarithm. In Y = log10(X), Y is the common (base-10)
logarithm of X. X must be non-zero positive.
Exponential. In Y = exp(X), Y is exponential of X (eX).
Radian conversion. In Y = DegToRad(X), Y is the angle X in units
of radians. X must be an angle in degrees.
Degree conversion. In Y = RadToDeg(X), Y is the angle X in units
of degrees. X must be an angle in radians.
Absolute value. In Y = abs(X), Y is the absolute value of X.
Square root. In Y = sqrt(X), Y is the square root of X. X must be
non-negative.
Numeric Manipula- mod
tion Functions
ceil
floor
fix
Modulus after division. mod(x,y) returns x - n*y, where
n = floor(x/y) if y ~= 0. By convention, mod(x,x) is x.
Round towards plus infinity. ceil(X) rounds X to the nearest
integer towards plus infinity.
Round towards minus infinity. floor(X) rounds X to the
nearest integer towards minus infinity.
Round towards zero. fix(X) rounds X to the nearest integer
towards zero.
681
Reference Guide
Random
Number
Functions
Assignment (=)
randn
rand
SetSeed
Matrix
Functions
norm
det
cross
inv
682
Normally distributed pseudorandom numbers. R = randn(N) returns an N-by-N matrix containing pseudorandom values drawn from
the standard normal distribution. R = randn() returns a single random number.
Uniformly distributed pseudorandom numbers. R = rand(N) returns an N-by-N matrix containing pseudorandom values drawn from
the standard uniform distribution on the open interval (0,1). R =
rand() returns a single random number.
Set seed for random number generation. SetSeed(X)sets the seed
for the random number generator where X must b a postive real number.
Note: SetSeed calls through to the C++ 11 random number generator seed algorithm that requires an unsigned integer. Since the GMAT
script language only supports real numbers, casting is performed by the
compiler which rounds the real number down to the nearest integer.
We recommend passing in real numbers with zero mantissa (i.e "1.0"
or "198.0").
2-norm. In Y = norm(X), Y is the 2-norm of X, where X must be a vector
(i.e. one dimension must be 1). If X is a scalar, Y is equal to X.
Determinant. In Y = det(X), Y is tthe cross product of the vectors A and
B. If X is a matrix, the number of rows must equal the number of columns.
If X is a scalar, Y is equal to X. For efficiency, GMAT’s implementation of
the determinant is currently limited to matrices 9×9 or smaller.
Vector cross product. In C = cross(A,B), C is the vector cross product
of A and B . A and B must be 3 element arrays.
Inverse. In Y = inv(X), Y is the inverse of X. X must be a matrix or
a scalar. If X is a matrix, the number of rows must equal the number of
columns. X^(-1) is an alternate syntax.
Reference Guide
Assignment (=)
String Manipulation strcat
Functions
strfind
strrep
strcmp
sprintf
String concatenation. STROUT = strcat(S1, S2, ...,
SN)concatenates strings. Inputs can be combinations of
string variables and string literals.
String find. INDEX = strfind(TEXT,PATTERN) returns
the starting index of the first instance of PATTERN in TEXT.
If PATTERN is not found, INDEX = -1.
String
replace.
NEWSTR
=
strrep(OLDSTR,OLDSUBSTR,NEWSUBSTR) replaces all
occurrences of the string OLDSUBSTR within string OLDSTR
with the string NEWSUBSTR.
String compare. FLAG = strcmp(S1,S2) compares the
strings S1 and S2 and returns logical 1 (true) if they are identical, and returns logical 0 (false) otherwise.
Write formatted data to a string. STRING
=
sprintf(FORMATSPEC, A, ...) formats data in
A,... according to FORMATSPEC which is a C-style format
spec.
Note: The GMAT sprintf function calls through to the
sprintf function in the c-library iostream. Additionally, the
GMAT script language does not support an integer data type,
only doubles.
A format spec follows this prototype:
%[flags][width]
[.precision][length]specifier
Specifiers
a
A
e
E
f
F
g
G
o
x
X
Hexadecimal floating point, lowercase.
Hexadecimal floating point, uppercase
Scientific notation (mantissa/exponent), lowercase
Scientific notation (mantissa/exponent), uppercase
Decimal floating point, lowercase
Decimal floating point, uppercase
Use the shortest representation: %e or %f
Use the shortest representation: %E or %F
Unsigned octal
Unsigned hexadecimal integer, lowercase
Unsigned hexadecimal integer, uppercase
683
Reference Guide
Flags
Assignment (=)
+
#
0
(space)
Forces to preceed the result with a plus or minus sign (+ or -) even for
positive numbers. By default, only negative numbers are preceded with
a - sign.
Left-justify within the given field width; Right justification is the default
(see width sub-specifier).
Used with o, x or X specifiers the value is preceeded with 0, 0x or 0X
respectively for values different than zero. Used with a, A, e, E, f, F, g or
G it forces the written output to contain a decimal point even if no more
digits follow. By default, if no digits follow, no decimal point is written.
Left-pads the number with zeroes (0) instead of spaces when padding
is specified (see width sub-specifier).
If no sign is going to be written, a blank space is inserted before the
value.
Width
Minimum number of characters to be printed. If the value to be printed is shorter
than this number, the result is padded with blank spaces. The value is not truncated
even if the result is larger.
Precision
For a, A, e, E, f and F specifiers: this is the number of digits to be printed after the
decimal point (by default, this is 6).
For g and G specifiers: This is the maximum number of significant digits to be
printed.
For s: this is the maximum number of characters to be printed. By default all characters are printed until the ending null character is encountered. If the period is
specified without an explicit value for precision, 0 is assumed.
Integer specifiers are not supported as GMAT does not have an integer data type
in the script language.
Examples
Evaluate a basic algebraic equation:
Create Variable A B C x y
x = 1
Create ReportFile aReport
BeginMissionSequence
A = 10
B = 20
C = 2
y = A*x^2 + B*x + C
Report aReport y
Matrix manipulation:
Create Array A[2,2] B[2,2] C[2,2] x[2,1] y[2,1]
684
Reference Guide
Assignment (=)
Create ReportFile aReport
A(1,1)
A(2,1)
A(1,2)
A(2,2)
=
=
=
=
10
5
.10
1
x(1,1) = 2
x(2,1) = 3
BeginMissionSequence
B = inv(A)
C = B'
y = C*x
Report aReport A B C x y
Cloning a resource:
Create Spacecraft Sat1 Sat2
Sat1.Cd = 1.87
Sat1.DryMass = 123.456
Create ReportFile aReport
BeginMissionSequence
Sat2 = Sat1
Report aReport Sat2.Cd Sat2.DryMass
Using built-in functions:
Create
Create
Create
Create
Variable pi x y1 y2 y3
Array A[3,3]
Spacecraft aSat
ReportFile aReport
BeginMissionSequence
pi = acos(-1)
aSat.TA = pi/4
x = pi/4
A(1,1) = pi/4
y1 = sin(x)
y2 = sin(aSat.TA)
y3 = sin(A(1,1))
Report aReport y1 y2 y3
685
686
Reference Guide
BeginFiniteBurn
Model finite thrust maneuvers
Script Syntax
BeginFiniteBurn aFiniteBurn(aSpacecraft)
EndFiniteBurn aFiniteBurn(aSpacecraft)
Description
When you apply a BeginFiniteBurn command, you turn on the thruster configuration given in
the specified FiniteBurn model. Similarly, when you apply an EndFiniteBurn command, you turn
off the thruster configuration in the specified FiniteBurn model. After GMAT executes a BeginFiniteBurn command, all propagation for the spacecraft affected by the FiniteBurn object will
include the configured finite thrust in the dynamics until an EndFiniteBurn line is executed for
that configuration. In order to apply a non-zero finite burn , there must be a Propagate command
between the BeginFiniteBurn and EndFiniteBurn commands.
To apply the BeginFiniteBurn and EndFiniteBurn commands, a FiniteBurn object must be configured. This object requires the configuration of ChemicalTank and ChemicalThruster models.
See the Remarks section and the examples below for a more detailed explanation.
See Also: Spacecraft, ChemicalThruster, ChemicalTank, FiniteBurn
Options
Option
Description
BeginFiniteBurn - Burn
Specifies the FiniteBurn object activated by the BeginFiniteBurn command.
Accepted Data Types
Allowed Values
Default Value
Required
Interfaces
BeginFiniteBurn - SpacecraftList
Reference Array
FiniteBurn resource
DefaultFB
yes
GUI, script
Specifies the Spacecraft (currently only a single Spacecraft
can be in this list) acted upon by the BeginFiniteBurn
command. The Spacecraft listed in SpacecraftList will
have thrusters activated according to the configuration of
the FiniteBurn object defined by the Burn field.
Accepted Data Types
Allowed Values
Default Value
Required
Interfaces
Reference Array
Spacecraft Objects
DefaultSC
yes
GUI, script
687
Reference Guide
BeginFiniteBurn
Option
Description
EndFiniteBurn - Burn
Specifies the FiniteBurn object de-activated by the
EndFiniteBurn command.
Accepted Data Types
Allowed Values
Default Value
Required
Interfaces
EndFiniteBurn - SpacecraftList
Reference Array
FiniteBurn Object
DefaultFB
yes
GUI, script
Specifies the Spacecraft (currently only a single Spacecraft can be in this list) acted upon by the EndFiniteBurn
command. Spacecraft listed in SpacecraftList will have
thrusters de-activated according to the configuration of the
FiniteBurn object defined by the Burn field.
Accepted Data Types
Allowed Values
Default Value
Required
Interfaces
Spacecraft
Spacecraft resource
DefaultSC
yes
GUI, script
GUI
The BeginFiniteBurn and EndFiniteBurn command dialog boxes allow you to implement a finite
burn by specifying which finite burn model should be used and which spacecraft the finite burn
should be applied to. The dialog boxes for BeginFiniteBurn and EndFiniteBurn are shown below.
688
BeginFiniteBurn
Reference Guide
Use the Burn menu to select the FiniteBurn model for the maneuver. Use the Spacecraft text box
to select the spacecraft for the finite burn. You can either type the spacecraft name in the Spacecraft
text box or click the Edit button and select the spacecraft using the ParameterSelectDialog box.
If you add a BeginFiniteBurn command or EndFiniteBurn command to the mission sequence,
without first creating a FiniteBurn object, GMAT will create a default FiniteBurn object called DefaultFB. However, you will need to configure the required ChemicalTank and ChemicalThruster
objects required for a FiniteBurn object before you can run the mission. See the Remarks section
for detailed instructions.
Remarks
Configuring a Finite Burn
To use the BeginFiniteBurn and EndFiniteBurn commands in your mission sequence, you must
configure a FiniteBurn object along with ChemicalTank and ChemicalThruster objects as shown
in the examples below and as described in these steps:
1. Create and configure a ChemicalTank model.
2. Create a ChemicalThruster model:
a. Set the parameters (direction, thrust, specific impulse, etc) for the thruster
b. Configure the ChemicalThruster to use the ChemicalTank created in Step 1.
3. Add the ChemicalTank and ChemicalThruster created in the previous two steps to the Spacecraft.
4. Create a FiniteBurn model and configure it to use the ChemicalThruster created in Step 2.
Initial Thruster Status
When you configure the Spacecraft, ChemicalTank, ChemicalThruster, and FiniteBurn objects,
GMAT initializes these objects with the thrusters turned off, so that no finite burns are active. You
must use the BeginFiniteBurn command to turn on the thruster if you want to apply a finite burn
during propagation.
689
Reference Guide
BeginFiniteBurn
Warning
Caution: If GMAT throws the error message “Propagator Exception: MassFlow is not
a known propagation parameter on DefaultSC”, then you have not configured all of the
required models to perform a finite burn. See detailed instructions above and examples
to configure models required by the EndFiniteBurn/BeginFiniteBurn commands.
BeginFiniteBurn and EndFiniteBurn commands are NOT branch commands
The BeginFiniteBurn and EndFiniteBurn commands are NOT branch commands, meaning, a
BeginFiniteBurn command can exist without an EndFiniteBurn command (however, this may
result in depleting all the fuel in the spacecraft model). For behavior when fuel mass is fully depleted
during a finite burn see the ChemicalTank object.
Similarly, since the BeginFiniteBurn and EndFiniteBurn commands are used to turn on or off
the thrusters, applying the same command multiple times in a script without its inverse is the same
as applying it once. In other words, if you do this:
BeginFiniteBurn aFiniteBurn(aSat)
BeginFiniteBurn aFiniteBurn(aSat)
BeginFiniteBurn aFiniteBurn(aSat)
The effect is the same as only applying the BeginFiniteBurn command one time. The same holds
true for the EndFiniteBurn command.
Examples
Perform a finite burn while the spacecraft is between true anomaly of 300 degrees and 60 degrees.
% Create objects
Create Spacecraft aSat
Create ChemicalThruster aThruster
Create ChemicalTank aTank
Create FiniteBurn aFiniteBurn
Create Propagator aPropagator
% Configure the physical objects
aSat.Thrusters
= {aThruster}
aThruster.Tank
= {aTank}
aSat.Tanks
= {aTank}
aFiniteBurn.Thrusters = {aThruster}
BeginMissionSequence
% Prop to TA = 300 then maneuver until TA = 60
Propagate aPropagator(aSat, {aSat.TA = 300})
BeginFiniteBurn aFiniteBurn(aSat)
Propagate aPropagator(aSat, {aSat.TA = 60})
690
BeginFiniteBurn
Reference Guide
EndFiniteBurn aFiniteBurn(aSat)
Perform a velocity direction maneuver firing the thruster for 2 minutes.
% Create objects
Create Spacecraft aSat
Create ChemicalThruster aThruster
Create ChemicalTank aTank
Create FiniteBurn aFiniteBurn
Create Propagator aPropagator
% Configure the physical objects
aThruster.CoordinateSystem = Local
aThruster.Origin = Earth
aThruster.Axes
= VNB
aThruster.ThrustDirection1 = 1
aThruster.ThrustDirection2 = 0
aThruster.ThrustDirection3 = 0
% Configure the physical objects
aSat.Thrusters
= {aThruster}
aThruster.Tank
= {aTank}
aSat.Tanks
= {aTank}
aFiniteBurn.Thrusters = {aThruster}
BeginMissionSequence
% Fire thruster for 2 minutes
BeginFiniteBurn aFiniteBurn(aSat)
Propagate aPropagator(aSat, {aSat.ElapsedSecs = 120})
EndFiniteBurn aFiniteBurn(aSat)
691
692
Reference Guide
BeginMissionSequence
Begin the mission sequence portion of a script
Script Syntax
BeginMissionSequence
Description
The BeginMissionSequence command indicates the end of resource initialization and the beginning of the mission sequence portion of a GMAT script. It must appear once as the first command
in the script, and must follow all resource creation lines.
See Also: Script Language
GUI
The BeginMissionSequence command is managed automatically when building mission sequences
using the GUI mission tree. However, when editing the GMAT script directly, either with the GMAT
script editor or with an external editor, you must insert the BeginMissionSequence command
manually.
Remarks
The BeginMissionSequence is a script-only command that is not needed when working from the
GUI. It indicates to GMAT that the portion of the script above the command consists of static
resource initialization that can be performed in any order, and that the portion below the command
consists of mission sequence commands that must be executed sequentially. This and other rules of
the scripting language are discussed in detail in the script language reference.
Examples
A minimal GMAT script that propagates a spacecraft:
Create Spacecraft aSat
Create Propagator aProp
BeginMissionSequence
Propagate aProp(aSat) {aSat.ElapsedDays = 1}
693
694
Reference Guide
BeginScript
Execute free-form script commands
Script Syntax
BeginScript
[script statements]
…
EndScript
Description
The BeginScript and EndScript commands (ScriptEvent in the GUI) allow you to write freeform script statements in the mission sequence without the statements being shown as individual
commands in the GMAT GUI. This is useful as a way to group and label a complex sequence of
statements as one unit, or to write small sequences of script statements when otherwise using the
GUI to create the mission sequence. Within the script itself, there is no difference in the execution
of statements within a BeginScript/EndScript block and those outside of it.
See Also: the section called “Script Editor”
GUI
The ScriptEvent GUI window divides the command into three parts: an initial comment, fixed
BeginScript and EndScript commands, and the content of the block itself. The scripting window
is a miniature version of the main script editor, and features line numbers, syntax highlighting, code
folding, and all of the editing tools available in the full editor. See the the section called “Script Editor” documentation for more information. The ScriptEvent window performs script syntax val695
Reference Guide
BeginScript
idation when changes are applied. Nested BeginScript/EndScript blocks in the script language
are collapsed into a single ScriptEvent when loaded into the GUI, and are saved to a single BeginScript/EndScript block when saved to a script.
Examples
Perform a calculation inside a BeginScript/EndScript block. When loaded into the GUI, the calculations within the BeginScript/EndScript block will be contained within a single ScriptEvent
command.
Create Spacecraft aSat
Create Propagator aProp
Create ImpulsiveBurn aBurn
Create Variable a_init v_init
Create Variable a_transfer v_transfer_1 v_transfer_2
Create Variable a_target v_final mu
Create Variable dv_1 dv_2
mu = 398600.4415
a_target = 42164
BeginMissionSequence
% calculate Hohmann burns
BeginScript
a_init = aSat.SMA
v_init = aSat.VMAG
a_transfer = (a_init + a_target) / 2
v_transfer_1 = sqrt(2*mu/a_init - mu/a_transfer)
v_transfer_2 = sqrt(2*mu/a_target - mu/a_transfer)
v_final = sqrt(mu/a_target)
dv_1 = v_transfer_1 - v_init
dv_2 = v_final - v_transfer_2
EndScript
% perform burn 1
aBurn.Element1 = dv_1
Maneuver aBurn(aSat)
Propagate aProp(aSat) {aSat.Apoapsis}
% perform burn 2
aBurn.Element1 = dv_2
Maneuver aBurn(aSat)
Propagate aProp(aSat) {aSat.ElapsedSecs = aSat.OrbitPeriod}
696
Reference Guide
CallGmatFunction
Call a GMAT function
Script Syntax
GmatFunction()
GmatFunction(input_argument[, input_argument]...)
[output_argument[, output_argument]...] = GmatFunction
[output_argument[, output_argument]...] = ...
GmatFunction(input_argument[, input_argument]...)
Description
GMAT provides a special command that allows you to call a GMAT function which is written via
GMAT's GmatFunction resource. In the GUI, the GMAT function is called through the CallGmatFunction command.
In the syntax description, GmatFunction is a GmatFunction resource that must be declared during
initialization. Arguments can be passed into the function as inputs and returned from the function
as outputs. See Remarks for details. Furthermore, data that is passed into the function as input
or received from the function as output can also be declared as global by using GMAT's Global
command. See the Global reference for more details.
See Also: GMATFunction, Global
GUI
The CallGmatFunction GUI provides two input boxes for input and output arguments and a list
to select a GMAt function to call.
The Output box lists all configured output argument parameters. These must be selected by clicking
Edit, which displays a ParameterSelectioDialog window. See the Calculation Parameters reference
for details on how to select a parameter.
697
Reference Guide
CallGmatFunction
The Input box is identical in behavior to Output, but lists all configured input arguments to the
function. Arguments must be selected by clicking Edit. The Function list displays all functions that
have been declared as GmatFunction resources in the Resources tree. Select a function from the
list to call it.
When the changes are accepted, GMAT does not perform any validation of input or output arguments. This validation is performed when the mission is actually run.
Remarks
GMAT objects can be passed into the GMAT function as input and can also be returned from
the function as output. If a given GMAT object is not declared as global in both the main script
and inside the GMAT function, then all objects that are passed into or received as output from the
function are considered to be local to that function and the main script.
Below is a list of allowed arguments that can be passed as input to the function and received as
output from the function. Also see GmatFunction resource's Remarks and Examples sections for
more details and distinct examples that show how to pass objects as inputs to the function, perform
an operation inside the function, then receive objects as outputs from the function.
The input arguments (input_argument values in the syntax description) can be any of the following types:
• Any resource objects (e.g. Spacecraft, Propagator, DC, Optimizers, Impulsive or FiniteBurns)
• resource parameter of real number type (e.g. Spacecraft.X)
• resource parameter of string type (e.g. Spacecraft.UTCGregorian)
• Array, String, or Variable resource
The output arguments can be any of the following types:
•
•
•
•
Resource object like Spacecraft
resource parameter of real number type (e.g. Spacecraft.X)
resource parameter of string type (e.g. Spacecraft.UTCGregorian)
Array, String, or Variable resource
Examples
Call two different functions. One function performs a simple cross product and the second function
performs a dot product.
Create ReportFile rf
rf.WriteHeaders = false
Create GmatFunction cross_product
cross_product.FunctionPath = ...
'C:\Users\rqureshi\Desktop\cross_product.gmf'
Create GmatFunction dot_product
dot_product.FunctionPath = ...
'C:\Users\rqureshi\Desktop\dot_product.gmf'
698
CallGmatFunction
Reference Guide
Create Array v1[3,1] v2[3,1] v3[3,1] ...
v4[3,1] v5[3,1]
Create Variable v6
Create String tempstring
BeginMissionSequence
v1(1,1)
v1(2,1)
v1(3,1)
v2(1,1)
v2(2,1)
v2(3,1)
v4(1,1)
v4(2,1)
v4(3,1)
v5(1,1)
v5(2,1)
v5(3,1)
=
=
=
=
=
=
=
=
=
=
=
=
1
2
3
4
5
6
1
2
3
4
-5
6
% Call function. Pass local arrays as input:
% Receive local array as output
[v3] = cross_product(v1, v2)
Report rf v3
% Call function. Pass local arrays as input:
% Receive local variable as output
GMAT [v6] = dot_product(v4, v5)
tempstring = '---------'
Report rf tempstring
Report rf v6
%%%%%% cross_product Function begins below:
function [cross] = cross_product(vec1,vec2)
Create Array cross[3,1]
BeginMissionSequence
cross(1,1) = vec1(2,1)*vec2(3,1) - vec1(3,1)*vec2(2,1)
cross(2,1) = -(vec1(1,1)*vec2(3,1) - vec1(3,1)*vec2(1,1))
cross(3,1) = vec1(1,1)*vec2(2,1) - vec1(2,1)*vec2(1,1)
699
Reference Guide
CallGmatFunction
%%%%%% dot_product Function begins below:
function [c] = dot_product(a1,b1)
Create Variable c
BeginMissionSequence
c = a1(1,1)*b1(1,1) + a1(2,1)*b1(2,1) + a1(3,1)*b1(3,1)
Call GMAT function and pass local spacecraft as input, perform simple operation inside the function,
then send out updated, local spacecraft to the main script. Finally report spacecraft old and updated
position vector to the local report file subscriber:
Create Spacecraft aSat
aSat.DateFormat = UTCGregorian;
aSat.Epoch = '01 Jan 2000 11:59:28.000'
aSat.CoordinateSystem = EarthMJ2000Eq
aSat.DisplayStateType = Cartesian
aSat.X = 7100
aSat.Y = 0
aSat.Z = 1300
Create ReportFile rf
rf.WriteHeaders = false
Create GmatFunction Spacecraft_In_Out
Spacecraft_In_Out.FunctionPath = ...
'C:\Users\rqureshi\Desktop\Spacecraft_In_Out.gmf'
BeginMissionSequence
% Report initial S/C Position to local 'rf':
Report rf aSat.X aSat.Y aSat.Z
% Call function. Pass local S/C as input:
% Receive updated local S/C:
[aSat] = Spacecraft_In_Out(aSat)
% Report updated S/C Position to local 'rf':
Report rf aSat.X aSat.Y aSat.Z
%%%%%%%%%% Function begins below:
700
CallGmatFunction
Reference Guide
function [aSat] = Spacecraft_In_Out(aSat)
% Create local S/C:
Create Spacecraft aSat
BeginMissionSequence
% Update the S/C Position vector:
% Send updated S/C back to main script:
aSat.X = aSat.X + 1000
aSat.Y = aSat.Y + 2000
aSat.Z = aSat.Z + 3000
701
702
Reference Guide
CallMatlabFunction
Call a MATLAB function
Script Syntax
MatlabFunction()
MatlabFunction(input_argument[, input_argument]...)
[output_argument[, output_argument]...] = MatlabFunction
[output_argument[, output_argument]...] = ...
MatlabFunction(input_argument[, input_argument]...)
Description
GMAT provides a special command that allows you to call a function written in the MATLAB
language or provided with the MATLAB software. In the GUI, this is the CallMatlabFunction
command.
In the syntax description, MatlabFunction is a MatlabFunction resource that must be declared
during initialization. Arguments can be passed into and returned from the function, though some
data-type limitations apply. See Remarks for details.
When a MATLAB function is called, GMAT opens a MATLAB command-line window in the background. This functionality requires that MATLAB be properly installed and configured on your system.
See Also: MatlabFunction, MATLAB Interface
GUI
The CallMatlabFunction GUI provides two input boxes for input and output arguments and a list
to select a function to call.
The Output box lists all configured output argument parameters. These must be selected by clicking
Edit, which displays a parameter selection window. See the Calculation Parameters reference for
details on how to select a parameter.
703
Reference Guide
CallMatlabFunction
The Input box