General Mission Analysis Tool (GMAT)

User Guide

The GMAT Development Team


Table of Contents

Documentation Overview
Using GMAT
Tutorials
Reference Guide
Using GMAT
1. Welcome to GMAT
Features Overview
Dynamics and Environment Modelling
Plotting, Reporting and Product Generation
Optimization and Targeting
Programming Infrastructure
Orbit Determination Infrastructure
Interfaces
Heritage
Licensing
Platform Support
Contributors
2. Getting Started
Installation
Running GMAT
Starting GMAT
Exiting GMAT
Sample Missions
Getting Help
3. Tour of GMAT
User Interfaces Overview
GUI Overview
Script Interface Overview
GUI/Script Interface Interactions and Rules
Resources Tree
Organization
Folder Menus
Resource Menus
Mission Tree
Mission Tree Display
View Filters Toolbar
Mission Sequence Menu
Command Menu
Docking/Undocking/Placement
Command Summary
Data Availability
Data Contents
Supported Commands
Coordinate Systems
Output Tree
Script Editor
Active Script
GUI/Script Synchronization
Scripts List
Edit Window
Find and Replace
File Controls
Save Status Indicator
4. Configuring GMAT
File Structure
bin
data
docs
extras
matlab
output
plugins
samples
userfunctions
Configuring Data Files
Leap Second and EOP files
Loading Custom Plugins
Configuring the MATLAB Inteface
Configuring the Python Inteface
User-defined Function Paths
Tutorials
5. Simulating an Orbit
Objective and Overview
Configure the Spacecraft
Rename the Spacecraft
Set the Spacecraft Epoch
Set the Keplerian Orbital Elements
Configure the Propagator
Rename the Propagator
Configure the Force Model
Configuring the Orbit View Plot
Configure the Propagate Command
Run and Analyze the Results
6. Simple Orbit Transfer
Objective and Overview
Configure Maneuvers, Differential Corrector, and Graphics
Create the Differential Corrector
Modify the Default Orbit View
Create the Maneuvers.
Configure the Mission Sequence
Configure the Initial Propagate Command
Create the Target Sequence
Create the Final Propagate Command
Configure the Target Sequence
Run the Mission
7. Target Finite Burn to Raise Apogee
Objective and Overview
Create and Configure Spacecraft Hardware and Finite Burn
Create a Thruster and a Fuel Tank
Modify Thruster1 Thrust Coefficients
Attach ChemicalTank1 and Thruster1 to DefaultSC
Create the Finite Burn Maneuver
Create the Differential Corrector and Target Control Variable
Configure the Mission Sequence
Configure the Initial Propagate Command
Create the Target Sequence
Configure the Target Sequence
Run the Mission
Inspect Orbit View and Message Window
Explore the Command Summary Reports
8. Mars B-Plane Targeting
Objective and Overview
Configure Fuel Tank, Spacecraft properties, Maneuvers, Propagators, Differential Corrector, Coordinate Systems and Graphics
Create Fuel Tank
Modify the DefaultSC Resource
Create the Maneuvers
Create the Propagators
Create the Differential Corrector
Create the Coordinate Systems
Create the Orbit Views
Configure the Mission Sequence
Create the First Target Sequence
Configure the First Target Sequence
Configure the Target desired B-plane Coordinates Command
Configure the Prop 3 Days Command
Configure the Prop 12 Days to TCM Command
Configure the Vary TCM.V Command
Configure the Vary TCM.N Command
Configure the Vary TCM.B Command
Configure the Apply TCM Command
Configure the Prop 280 Days Command
Configure the Prop to Mars Periapsis Command
Configure the Achieve BdotT Command
Configure the Achieve BdotR Command
Run the Mission with first Target Sequence
Create the Second Target Sequence
Create the Final Propagate Command
Configure the second Target Sequence
Configure the Mars Capture Command
Configure the Vary MOI.V Command
Configure the Apply MOI Command
Configure the Prop to Mars Apoapsis Command
Configure the Achieve RMAG Command
Run the Mission with first and second Target Sequences
9. Optimal Lunar Flyby using Multiple Shooting
Objective and Overview
Configure Coordinate Systems, Spacecraft, Optimizer, Propagators, Maneuvers, Variables, and Graphics
Create a Moon-centered Coordinate System
Create the Spacecraft
Create the Propagators
Create the Maneuvers
Create the User Variables
Create the Optimizer
Create the 3-D Graphics
Create XPPlots/Reports
Configure the Mission Sequence
Overview of the Mission Sequence
Define Initial Guesses
Initialize Variables
Vary and Set Spacecraft Epochs
Vary Control Point States
Apply Constraints at Control Points
Propagate the Segments
Compute Some Quantities and Apply Patch Constraints
Apply Patch Point Constraints
Apply Constraints on Mission Orbit
Apply Cost Function
Design the Trajectory
Overview
Step 1: Verify Your Configuration
Step 2: Find a Smooth Trajectory
Step 5: Apply a New Constraint
10. Mars B-Plane Targeting Using GMAT Functions
Objective and Overview
Configure Fuel Tank, Spacecraft properties, Maneuvers, Propagators, Differential Corrector, Coordinate Systems and Graphics
Create Fuel Tank
Modify the DefaultSC Resource
Create the Maneuvers
Create the Propagators
Create the Differential Corrector
Create the Coordinate Systems
Create the Orbit Views
Create single Report File
Create a GMAT Function
Configure the Mission Sequence
Create Commands to Initiate the First Target Sequence
Configure the Mission Tree to Run the First Target Sequence
Configure the Make Objects Global Command
Configure the Target Desired B-Plane Coord. From Inside Function Command
Configure the Report Parameters Command
Run the Mission with first Target Sequence
Create the Second Target Sequence
Create the Final Propagate Command
Configure the second Target Sequence
Configure the Mars Capture Command
Configure the Vary MOI.V Command
Configure the Apply MOI Command
Configure the Prop to Mars Apoapsis Command
Configure the Achieve RMAG Command
Run the Mission with first and second Target Sequences
11. Finding Eclipses and Station Contacts
Objective and Overview
Load the Mission
Configure GMAT for Event Location
Verify SolarSystem Configuration
Configure CelestialBody Resources
Configure and Run the Eclipse Locator
Create and Configure the EclipseLocator
Run the Mission
Configure and Run the Contact Locator
Create and Configure a Ground Station
Create and Configure the ContactLocator
Run the Mission
Further Exercises
12. Electric Propulsion
Objective and Overview
Create and Configure Spacecraft Hardware and Finite Burn
Create a Thruster, Fuel Tank, and Solar Power System
Configure the Hardware
Attach Hardware to the Spacecraft
Create the Finite Burn Maneuver
Configure the Mission Sequence
Create the Commands
Configure the Propagate Command
Run the Mission
13. Simulate DSN Range and Doppler Data
Objective and Overview
Create and configure the spacecraft, spacecraft transponder, and related parameters
Create a satellite and set its epoch and Cartesian coordinates
Create a Transponder object and attach it to our spacecraft
Create and configure the Ground Station and related parameters
Create Ground Station Transmitter, Receiver, and Antenna objects
Create Ground Station
Create Ground Station Error Models
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 more realistic GMAT Measurement Data (GMD)
References
Appendix A – Determination of Measurement Noise Values
14. Orbit Estimation using DSN Range and Doppler Data
Objective and Overview
Create and configure the spacecraft, spacecraft transponder, and related parameters
Create a satellite and set its epoch and Cartesian coordinates
Create a Transponder object and attach it to our spacecraft
Create and configure the Ground Station and related parameters
Create Ground Station Transmitter, Receiver, and Antenna objects
Create Ground Station
Create Ground Station Error Models
Define the types of measurements that will be processed
Create and configure Force model and propagator
Create and configure BatchEstimatorInv object
Run the mission and analyze the results
Message Window Output
Plots of Observation Residuals
Batch Estimator Output Report
Matlab Output File
References
Appendix A – GMAT Message Window Output
Appendix B – Zeroth Iteration Plots of Observation Residuals
Appendix C – First Iteration Plots of Observation Residuals
Reference Guide
I. Resources
Antenna — Transmits or receives an RF signal.
Array — A user-defined one- or two-dimensional array variable
Barycenter — The center of mass of selected celestial bodies
BatchEstimatorInv — A batch least squares estimator
CelestialBody — A celestial body model
CoordinateSystem — An axis and origin pair
ContactLocator — A line-of-sight event locator between a target Spacecraft and an observer GroundStation
DifferentialCorrector — A numerical solver
ElectricTank — A model of a tank containing fuel for an electric propulsion system
ElectricThruster — An electric thruster model
EclipseLocator — A Spacecraft eclipse event locator
EphemerisFile — Generate spacecraft’s ephemeris data
ErrorModel — Used to specify measurement noise for simulation and estimation, and to apply or estimate measurement biases.
FileInterface — An interface to a data file
FiniteBurn — A finite burn
FminconOptimizer — The Sequential Quadratic Programming (SQP) optimizer, fmincon
Formation — A collection of spacecraft.
ChemicalTank — Model of a chemical fuel tank
GMATFunction — Declaration of a GMAT function
GroundStation — A ground station model.
GroundTrackPlot — A user-defined resource that draws longitude and latitude time-history of a spacecraft
ImpulsiveBurn — An impulsive maneuver
LibrationPoint — An equilibrium point in the circular, restricted 3-body problem
MatlabFunction — Declaration of an external MATLAB function
NuclearPowerSystem — A nuclear power system
OrbitView — A user-defined resource that plots 3-Dimensional trajectories
Propagator — A propagator models spacecraft motion
Receiver — Hardware that receives an RF signal.
ReportFile — Report data to a text file
Simulator — Configures the generation of simulated tracking data measurements.
SNOPT — The Sequential Quadratic Programming (SQP) optimizer, SNOPT
SolarPowerSystem — A solar power system model
SolarSystem — High level solar system configuration options
Spacecraft — A spacecraft model
Spacecraft Attitude — The spacecraft attitude model
Spacecraft Ballistic/Mass Properties — The physical properties of the spacecraft
Spacecraft Epoch — The spacecraft epoch
Spacecraft Hardware — Add hardware to a spacecraft
Spacecraft Navigation — There are a number of Spacecraft fields that are used exclusively to support GMAT's navigation capability.
Spacecraft Orbit State — The orbital initial conditions
Spacecraft Visualization Properties — The visual properties of the spacecraft
StatisticsAcceptFilter — Allows selection of data subsets for processing by the batch least squares estimator.
StatisticsRejectFilter — Allows selection of data subsets for processing by the batch least squares estimator.
String — A user-defined string variable
TrackingFileSet — Manages the observation data contained in one or more external tracking data files.
Transmitter — Defines the electronics hardware, attached to a GroundStation resource, that transmits an RF signal.
Transponder — Defines the electronics hardware, typically attached to a spacecraft, that receives and automatically re-transmits an incoming signal.
ChemicalThruster — A chemical thruster model
Variable — A user-defined numeric variable
VF13ad — The Sequential Quadratic Programming (SQP) optimizer, VF13ad
XYPlot — Plots data onto the X and Y axes of a graph
II. Commands
Achieve — Specify a goal for a Target sequence
Assignment (=) — Set a variable or resource field to a value, possibly using mathematical expressions
BeginFiniteBurn — Model finite thrust maneuvers
BeginMissionSequence — Begin the mission sequence portion of a script
BeginScript — Execute free-form script commands
CallGmatFunction — Call a GMAT function
CallMatlabFunction — Call a MATLAB function
CallPythonFunction — Call a Python function
ClearPlot — Allows you to clear all data from an XYPlot
EndFiniteBurn — Model finite thrust maneuvers in the mission sequence
FindEvents — Execute an event location search
For — Execute a series of commands a specified number of times
GetEphemStates() — Function used to output initial and final spacecraft states from an ephemeris file
Global — Declare Objects as global
If — Conditionally execute a series of commands
Maneuver — Perform an impulsive (instantaneous) maneuver
MarkPoint — Allows you to add a special mark point character on an XYPlot
Minimize — Define the cost function to minimize
NonlinearConstraint — Specify a constraint used during optimization
Optimize — Solve for condition(s) by varying one or more parameters
PenUpPenDown — Allows you to stop or begin drawing data on a plot
Propagate — Propagates spacecraft to a requested stopping condition
Report — Allows you to write data to a text file
RunEstimator — Ingests navigation measurements and generates an estimated state vector
RunSimulator — Generates simulated navigation measurements
Set — Configure a resource from a data interface
Stop — Stop mission execution
Target — Solve for condition(s) by varying one or more parameters
Toggle — Allows you to turn data output off or on
Vary — Specifies variables used by a solver
While — Execute a series of commands repeatedly while a condition is met
Write — Writes data to one or more of the following three destinations: the message window, the log file, or a ReportFile resource.
III. System
Calculation Parameters — Resource properties available for use by commands and output
Color — Color support in GMAT resources and commands
Command-Line Usage — Starting the GMAT application from the command line
#Include Macro — Load or import a script snippet
Keyboard Shortcuts — Keyboard shortcuts in the graphical user interface
MATLAB Interface — Interface to MATLAB system
Python Interface — Interface to the Python programming language
Script Language — The GMAT script language
Startup File — The gmat_startup_file.txt configuration file
Release Notes
GMAT R2016a Release Notes
New Features
Improvements
Compatibility Changes
Development and Tools
Known & Fixed Issues
GMAT R2015a Release Notes
New Features
Improvements
Compatibility Changes
Development and Tools
Known & Fixed Issues
GMAT R2014a Release Notes
New Features
Improvements
Compatibility Changes
Known & Fixed Issues
GMAT R2013b Release Notes
New Features
Improvements
Compatibility Changes
Known & Fixed Issues
GMAT R2013a Release Notes
Licensing
Major Improvements
Minor Enhancements
Compatibility Changes
Known & Fixed Issues
GMAT R2012a Release Notes
New Features
Improvements
Compatibility Changes
Known & Fixed Issues
GMAT R2011a Release Notes
New Features
Improvements
Compatibility Changes
Fixed Issues
Known Issues
Index

List of Figures

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

List of Tables

5.1. Sat Orbit State Settings
6.1. DefaultOrbitView settings
6.2. Additional Target Sequence Commands
7.1. Additional Target Sequence Commands
8.1. MainTank settings
8.2. MAVEN settings
8.3. NearEarth settings
8.4. DeepSpace settings
8.5. NearMars settings
8.6. EarthView settings
8.7. SolarSystemView settings
8.8. MarsView settings
8.9. Additional First Target Sequence Commands
8.10. Additional Second Target Sequence Commands
10.1. MainTank settings
10.2. MAVEN settings
10.3. NearEarth settings
10.4. DeepSpace settings
10.5. NearMars settings
10.6. EarthView settings
10.7. SolarSystemView settings
10.8. MarsView settings
10.9. Additional Second Target Sequence Commands
24. Multiple platforms
25. Windows
26. Mac OS X
27. Linux

Documentation Overview

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

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

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

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

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

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

Note

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

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

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

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

The Mars B-Plane Targeting tutorial shows how to 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.

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.

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

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

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

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

Note

This document uses two typographical conventions throughout:

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

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

Using GMAT

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

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

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

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

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

Note

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

Chapter 1. Welcome to GMAT

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

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

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

Chapter 2. Getting Started

Installation

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

The following packages are available for the major platforms:

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

Installer

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

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

Binary Bundle

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

Source Code

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

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

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

There are tags available for reach release.

Running GMAT

Starting GMAT

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

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

Exiting GMAT

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

Sample Missions

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

  1. Open GMAT.

  2. On the toolbar click Open.

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

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

  5. Click Run ().

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

Getting Help

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

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

  • Wiki: http://gmatcentral.org

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

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

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

  • Official contact:

Chapter 3. Tour of GMAT

User Interfaces Overview

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

GUI Overview

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

Windows GUI

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

Figure 3.1. GMAT Desktop (Windows)

GMAT Desktop (Windows)

Menu Bar

The menu bar contains File, Edit, Window and Help functionality.

On Windows, the File menu contains standard Open, Save, Save As, and Exit functionality as well as Open Recent. The Edit menu contains functionality for script editing when the script editor is active. The Window menu contains tools for organizing graphics windows and the script editor within the GMAT desktop. Examples include the ability to Tile windows, Cascade windows and Close windows. The Help menu contains links to Online Help, Tutorials, Forums, and the Report An Issue option links to GMAT’s defect reporting system, the Welcome Page, and a Provide Feedback link.

Toolbar

The toolbar provides easy access to frequently used controls such as file controls, Run, Pause, and Stop for mission execution, and controls for graphics animation. On Windows and Linux, the toolbar is located at the top of the GMAT window; on the Mac, it is located on the left of the GMAT frame. Because the toolbar is vertical on the Mac, some toolbar options are abbreviated.

GMAT allows you to simultaneously edit the raw script file representation of your mission and the GUI representation of your mission. It is possible to make inconsistent changes in these mission representations. The GUI/Script Sync Status indicator located in the toolbar shows you the state of the two mission representations. See the the section called “GUI/Script Interactions and Synchronization” section for further discussion.

Resources Tab

The Resources tab brings the Resources tree to the foreground of the desktop.

Resources Tree

The Resources tree displays all configured GMAT resources and organizes them into logical groups. All objects created in a GMAT script using a Create command are found in the Resources tree in the GMAT desktop.

Mission Tab

The Mission tab brings the Mission Tree to the foreground of the desktop.

Mission Tree

The Mission tree displays GMAT commands that control the time-ordered sequence of events in a mission. The Mission tree contains all script lines that occur after the BeginMissionSequence command in a GMAT script. You can undock the Mission tree as shown in the figure below by right-clicking on the Mission tab and dragging it into the graphics window. You can also follow these steps:

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

  2. Right-click on the Mission Sequence folder in the Mission tree and select Undock Mission Tree in the menu.

Figure 3.2. Undocked Mission Tree

Undocked Mission Tree

Output Tab

The Output tab brings the Output Tree to the foreground of the desktop.

Output Tree

The Output tree contains GMAT output such as report files and graphical displays.

Message Window

When you run a mission in GMAT, information including warnings, errors, and progress are written to the message window. For example, if there is a syntax error in a script file, a detailed error message is written to the message window.

Status Bar

The status bar contains various informational messages about the state of the GUI. When a mission is running, a Busy indicator will appear in the left pane. The center pane displays the latitude and logitude of the mouse cursor as it moves over a ground track window.

Script Interface Overview

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

Figure 3.3. GMAT Script Editor

GMAT Script Editor

Scripts Folder

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

Script Status Box

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

Save,Sync Button

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

Save,Sync,Run Button

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

Save As Button

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

Close

The Close button closes the script editor.

GUI/Script Interface Interactions and Rules

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

GUI/Script Interactions and Synchronization

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

Caution

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

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

How the GUI Maps to a Script

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

Caution

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

How the Script Maps to the GUI

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

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

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

Basic Script Syntax Rules

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

  • GMAT commands are not allowed before the BeginMissionSequence command.

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

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

  • GMAT’s script language is case-sensitive.

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

Resources Tree

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

Figure 3.4. Default Resources tree

Default Resources tree

Organization

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

Folder Menus

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

Figure 3.5. Folder menu for Spacecraft

Folder menu for Spacecraft

Figure 3.6. Folder menu for Hardware

Folder menu for Hardware

Resource Menus

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

Figure 3.7. Resource menu

Resource menu

Open/Close

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

Rename

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

  • Folder names (eg, Spacecraft)

  • Command names (eg, Propagate)

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

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

  • Names with spaces

Delete

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

  • Default coordinate systems

    • EarthMJ2000Eq

    • EarthMJ2000Ec

    • EarthFixed

    • EarthICRF

  • Default planetary bodies

    • Sun

    • Mercury

    • Venus

    • Earth

    • Luna

    • Mars

    • Jupiter

    • Saturn

    • Uranus

    • Neptune

    • Pluto

Clone

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

  • Default coordinate systems (listed above)

  • Default planetary bodies (listed above)

  • Propagator resource objects

Mission Tree

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

Warning

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

Mission Tree Display

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

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

Note

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

View Filters Toolbar

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

  • Filter by branch level

  • Filter by command types (inclusive)

  • Filter by command types (exclusive)

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

Note

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

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

Filter by Branch Level

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

  • Show all branches

  • Show one level of branching

  • Show two levels of branching

  • Show three levels of branching

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

Filter by Command Types

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

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

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

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

  • ScriptEvent commands

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

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

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

  • Report

  • Equation

  • Output-related (Report, Toggle, PenUp, PenDown, MarkPoint, and ClearPlot)

  • Function calls (CallMatlabFunction)

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

Note

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

Mission Sequence Menu

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

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

Mission Sequence Menu Options:

Collapse All

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

Expand All

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

Append

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

Run

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

Show Detail

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

Show Mission Sequence

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

Show Script

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

Mission Summary - All

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

Mission Summary - Physics

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

Dock Mission Tree

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

Undock Mission Tree

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

Command Menu

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

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

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

  • Achieve commands can only appear inside of a Target sequence.

  • Vary commands can only appear in a Target or Optimize sequence,

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

Command Menu Options

Open

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

Close

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

Append

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

Insert After

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

Insert Before

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

Rename

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

Delete

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

Command Summary

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

Docking/Undocking/Placement

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

To undock the Mission Tree Display, either:

  • Right click and drag the Mission tab out of the Resource Tree window.

  • Right click the Mission Sequence home item and select Undock Mission Tree.

To dock the Mission Tree display, either:

  • Left click the close button (x) of the undocked Mission Tree window.

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

Command Summary

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

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

Snapshot of a sample Command Summary is shown in the following figure.

Data Availability

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

Data Contents

The Command Summary contains several types of data. Orbit state representations include Cartesian, spherical, and Keplerian. For hyperbolic orbits, B-Plane coordinates, DLA and RLA are provided. Planetodetic information includes Longitude and Latitude among others. For a Maneuver command, the Maneuver properties are displayed in the CoordinateSystem specified on the ImpulsiveBurn resource. 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                       Spherical State 
        ---------------------------           ------------------------------ 
        X  =   7047.3574396928 km             RMAG =   7195.1179781105 km
        Y  =  -821.00373455465 km             RA   =  -6.6448962577676 deg 
        Z  =   1196.0053110175 km             DEC  =   9.5683789596091 deg 
        VX =   0.8470865225276 km/sec         VMAG =   7.4415324037805 km/s
        VY =   7.3062391027010 km/sec         AZI  =   81.377585410118 deg
        VZ =   1.1303623817297 km/sec         VFPA =   88.583915406742 deg  
                                              RAV  =   83.386645244484 deg
                                              DECV =   8.7370006427902 deg

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

Output Tree

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

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

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

A populated Output tree is shown in the following figure.

Script Editor

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

  • GUI/script synchronization

  • Mission execution from the editor

  • Syntax highlighting

  • Comment/uncomment or indent blocks of text

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

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

Figure 3.8. Parts of the script editor

Parts of the script editor

Active Script

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

Figure 3.9. Active script indicators

Active script indicators

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

GUI/Script Synchronization

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

Synchronized

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

Script Modified

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

GUI Modified

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

Unsynchronized

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

Script Error

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

Warning

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

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

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

  1. Saves any modifications to the script

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

  3. Validates the script file

  4. Refreshes the GUI by loading the saved script

  5. Sets GUI/Script Sync Status to Synchronized.

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

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

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

Scripts List

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

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

  • Open: opens the script in the edit window

  • Close: closes any open edit windows for this script

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

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

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

  • Remove: removes the script from the script list

Edit Window

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

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

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

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

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

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

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

  • Delete: Delete the current selection

  • Select All: Select the entire script contents

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

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

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

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

  • Select All: Select the entire script contents

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

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

  • Goto: Place the cursor on a specific line number

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

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.

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

Save Status Indicator

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

Chapter 4. Configuring GMAT

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

File Structure

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

Figure 4.1. GMAT Root Directory Structure

GMAT Root Directory Structure

bin

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

data

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

Figure 4.2. GMAT Data Directory Structure

GMAT Data Directory Structure

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

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

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

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

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

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

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

docs

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

extras

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

matlab

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

output

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

plugins

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

samples

The samples directory contains 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.

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.62-now 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 tai-utc.dat file for all time computations requiring leap seconds that are not performed by the SPICE utilities. When a new leap second is added, you can replace this file with the new file from the US Naval Observatory. In addtion, you can modify the file if a new leap second is added by simply duplicating the last row and updating it with the correct information for the new leap second. For example, if a new leapsecond were added on 01 Jul 2013, you would add the following line to the bottom of tai-utc.dat:

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

Loading Custom Plugins

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

Configuring the MATLAB Inteface

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

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.

Tutorials

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

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

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

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

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

Table of Contents

5. Simulating an Orbit
Objective and Overview
Configure the Spacecraft
Rename the Spacecraft
Set the Spacecraft Epoch
Set the Keplerian Orbital Elements
Configure the Propagator
Rename the Propagator
Configure the Force Model
Configuring the Orbit View Plot
Configure the Propagate Command
Run and Analyze the Results
6. Simple Orbit Transfer
Objective and Overview
Configure Maneuvers, Differential Corrector, and Graphics
Create the Differential Corrector
Modify the Default Orbit View
Create the Maneuvers.
Configure the Mission Sequence
Configure the Initial Propagate Command
Create the Target Sequence
Create the Final Propagate Command
Configure the Target Sequence
Run the Mission
7. Target Finite Burn to Raise Apogee
Objective and Overview
Create and Configure Spacecraft Hardware and Finite Burn
Create a Thruster and a Fuel Tank
Modify Thruster1 Thrust Coefficients
Attach ChemicalTank1 and Thruster1 to DefaultSC
Create the Finite Burn Maneuver
Create the Differential Corrector and Target Control Variable
Configure the Mission Sequence
Configure the Initial Propagate Command
Create the Target Sequence
Configure the Target Sequence
Run the Mission
Inspect Orbit View and Message Window
Explore the Command Summary Reports
8. Mars B-Plane Targeting
Objective and Overview
Configure Fuel Tank, Spacecraft properties, Maneuvers, Propagators, Differential Corrector, Coordinate Systems and Graphics
Create Fuel Tank
Modify the DefaultSC Resource
Create the Maneuvers
Create the Propagators
Create the Differential Corrector
Create the Coordinate Systems
Create the Orbit Views
Configure the Mission Sequence
Create the First Target Sequence
Configure the First Target Sequence
Configure the Target desired B-plane Coordinates Command
Configure the Prop 3 Days Command
Configure the Prop 12 Days to TCM Command
Configure the Vary TCM.V Command
Configure the Vary TCM.N Command
Configure the Vary TCM.B Command
Configure the Apply TCM Command
Configure the Prop 280 Days Command
Configure the Prop to Mars Periapsis Command
Configure the Achieve BdotT Command
Configure the Achieve BdotR Command
Run the Mission with first Target Sequence
Create the Second Target Sequence
Create the Final Propagate Command
Configure the second Target Sequence
Configure the Mars Capture Command
Configure the Vary MOI.V Command
Configure the Apply MOI Command
Configure the Prop to Mars Apoapsis Command
Configure the Achieve RMAG Command
Run the Mission with first and second Target Sequences
9. Optimal Lunar Flyby using Multiple Shooting
Objective and Overview
Configure Coordinate Systems, Spacecraft, Optimizer, Propagators, Maneuvers, Variables, and Graphics
Create a Moon-centered Coordinate System
Create the Spacecraft
Create the Propagators
Create the Maneuvers
Create the User Variables
Create the Optimizer
Create the 3-D Graphics
Create XPPlots/Reports
Configure the Mission Sequence
Overview of the Mission Sequence
Define Initial Guesses
Initialize Variables
Vary and Set Spacecraft Epochs
Vary Control Point States
Apply Constraints at Control Points
Propagate the Segments
Compute Some Quantities and Apply Patch Constraints
Apply Patch Point Constraints
Apply Constraints on Mission Orbit
Apply Cost Function
Design the Trajectory
Overview
Step 1: Verify Your Configuration
Step 2: Find a Smooth Trajectory
Step 5: Apply a New Constraint
10. Mars B-Plane Targeting Using GMAT Functions
Objective and Overview
Configure Fuel Tank, Spacecraft properties, Maneuvers, Propagators, Differential Corrector, Coordinate Systems and Graphics
Create Fuel Tank
Modify the DefaultSC Resource
Create the Maneuvers
Create the Propagators
Create the Differential Corrector
Create the Coordinate Systems
Create the Orbit Views
Create single Report File
Create a GMAT Function
Configure the Mission Sequence
Create Commands to Initiate the First Target Sequence
Configure the Mission Tree to Run the First Target Sequence
Configure the Make Objects Global Command
Configure the Target Desired B-Plane Coord. From Inside Function Command
Configure the Report Parameters Command
Run the Mission with first Target Sequence
Create the Second Target Sequence
Create the Final Propagate Command
Configure the second Target Sequence
Configure the Mars Capture Command
Configure the Vary MOI.V Command
Configure the Apply MOI Command
Configure the Prop to Mars Apoapsis Command
Configure the Achieve RMAG Command
Run the Mission with first and second Target Sequences
11. Finding Eclipses and Station Contacts
Objective and Overview
Load the Mission
Configure GMAT for Event Location
Verify SolarSystem Configuration
Configure CelestialBody Resources
Configure and Run the Eclipse Locator
Create and Configure the EclipseLocator
Run the Mission
Configure and Run the Contact Locator
Create and Configure a Ground Station
Create and Configure the ContactLocator
Run the Mission
Further Exercises
12. Electric Propulsion
Objective and Overview
Create and Configure Spacecraft Hardware and Finite Burn
Create a Thruster, Fuel Tank, and Solar Power System
Configure the Hardware
Attach Hardware to the Spacecraft
Create the Finite Burn Maneuver
Configure the Mission Sequence
Create the Commands
Configure the Propagate Command
Run the Mission
13. Simulate DSN Range and Doppler Data
Objective and Overview
Create and configure the spacecraft, spacecraft transponder, and related parameters
Create a satellite and set its epoch and Cartesian coordinates
Create a Transponder object and attach it to our spacecraft
Create and configure the Ground Station and related parameters
Create Ground Station Transmitter, Receiver, and Antenna objects
Create Ground Station
Create Ground Station Error Models
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 more realistic GMAT Measurement Data (GMD)
References
Appendix A – Determination of Measurement Noise Values
14. Orbit Estimation using DSN Range and Doppler Data
Objective and Overview
Create and configure the spacecraft, spacecraft transponder, and related parameters
Create a satellite and set its epoch and Cartesian coordinates
Create a Transponder object and attach it to our spacecraft
Create and configure the Ground Station and related parameters
Create Ground Station Transmitter, Receiver, and Antenna objects
Create Ground Station
Create Ground Station Error Models
Define the types of measurements that will be processed
Create and configure Force model and propagator
Create and configure BatchEstimatorInv object
Run the mission and analyze the results
Message Window Output
Plots of Observation Residuals
Batch Estimator Output Report
Matlab Output File
References
Appendix A – GMAT Message Window Output
Appendix B – Zeroth Iteration Plots of Observation Residuals
Appendix C – First Iteration Plots of Observation Residuals

Chapter 5. Simulating an Orbit

Audience

Beginner

Length

30 minutes

Prerequisites

None

Script File

Tut_SimulatingAnOrbit.script

Objective and Overview

Note

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

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

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

  2. Configure a Propagator.

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

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

  5. Run the mission and analyze the results.

Configure the Spacecraft

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

Rename the Spacecraft

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

  2. Type Sat.

  3. Click OK.

Set the Spacecraft Epoch

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

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

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

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

Set the Keplerian Orbital Elements

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

  2. In the SMA box, type 83474.318.

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

    Table 5.1. Sat Orbit State Settings

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


  4. Click OK.

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

Figure 5.1. Spacecraft State Setup

Spacecraft State Setup

Configure the Propagator

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

Rename the Propagator

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

  2. Type LowEarthProp.

  3. Click OK.

Configure the Force Model

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

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

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

  3. In the Order box, type 10.

  4. In Atmosphere Model list, click JacchiaRoberts.

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

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

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

  8. Click OK to close the CelesBodySelectDialog.

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

  10. Click OK.

Figure 5.2. Force Model Configuration

Force Model Configuration

Configuring the Orbit View Plot

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

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

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

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

  4. Click OK.

Figure 5.3. DefaultOrbitView Configuration

DefaultOrbitView Configuration

Configure the Propagate Command

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

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

  2. Double-click Propagate1.

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

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

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

    Figure 5.4. Propagate Command ParameterSelectDialog Configuration

    Propagate Command ParameterSelectDialog Configuration

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

  7. Click OK.

Figure 5.5. Propagate Command Configuration

Propagate Command Configuration

Run and Analyze the Results

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

  1. Click Save () to save your mission.

  2. Click the Run ().

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

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

  2. Display the command summary:

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

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

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

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

Figure 5.6. Orbit View Plot after Mission Run

Orbit View Plot after Mission Run

Chapter 6. Simple Orbit Transfer

Audience

Beginner

Length

30 minutes

Prerequisites

Complete Simulating an Orbit

Script File

Tut_SimpleOrbitTransfer.script

Objective and Overview

Note

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

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

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

  1. Create and configure a DifferentialCorrector resource.

  2. Modify the DefaultOrbitView to visualize the trajectory.

  3. Create two ImpulsiveBurn resources with default settings.

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

  5. Run the mission and analyze the results.

Configure Maneuvers, Differential Corrector, and Graphics

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

Create the Differential Corrector

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

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

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

Modify the Default Orbit View

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

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

  2. Set the values shown in the table below.

    Table 6.1. DefaultOrbitView settings

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


  3. Click OK to save these changes.

Create the Maneuvers.

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

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

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

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

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

Configure the Mission Sequence

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

Configure the Initial Propagate Command

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

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

  3. Rename Propagate1 to Prop To Periapsis.

Create the Target Sequence

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

Figure 6.1. Final Mission Sequence for the Hohmann Transfer

Final Mission Sequence for the Hohmann Transfer

To create the Target sequence:

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

  2. Right-click Target1 and click Rename.

  3. Type Hohmann Transfer and click OK.

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

  5. Rename Vary1 to Vary TOI.

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

    Table 6.2. Additional Target Sequence Commands

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


Note

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

Create the Final Propagate Command

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

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

  2. Rename Propagate3 to Prop One Day.

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

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

  5. Click OK to save these changes.

Figure 6.2. Prop One Day Command Configuration

Prop One Day Command Configuration

Configure the Target Sequence

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

Configure the Vary TOI Command

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

  2. In the Initial Value box, type 1.0.

  3. In the Max Step box, type 0.5.

  4. Click OK to save these changes.

Figure 6.3. Vary TOI Command Configuration

Vary TOI Command Configuration

Configure the Perform TOI Command

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

  2. Click OK.

Figure 6.4. Perform TOI Command Configuration

Perform TOI Command Configuration

Configure the Prop to Apoapsis Command

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

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

  3. Click OK to save these changes.

Figure 6.5. Prop to Apoapsis Command Configuration

Prop to Apoapsis Command Configuration

Configure the Achieve RMAG = 42165 Command

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

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

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

  4. Click OK to save these changes.

Figure 6.6. Achieve RMAG = 42165 Command Configuration

Achieve RMAG = 42165 Command Configuration

Configure the Vary GOI Command

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

  2. Next to Variable, click the Edit button.

  3. Under Object List, click GOI.

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

    Figure 6.7. Vary GOI Parameter Selection

    Vary GOI Parameter Selection

  5. Click OK to close the ParameterSelectDialog window.

  6. In the Initial Value box, type 1.0.

  7. In the MaxStep text box, type 0.2.

  8. Click OK to save these changes.

Figure 6.8. Vary GOI Command Configuration

Vary GOI Command Configuration

Configure the Perform GOI Command

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

  2. In the Burn list, click GOI.

  3. Click OK to save these changes.

Figure 6.9. Perform GOI Command Configuration

Perform GOI Command Configuration

Configure the Achieve ECC = 0.005 Command

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

  2. Next to Goal, click the Edit button.

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

  4. Click OK to close the ParameterSelectDialog window.

  5. In the Value box, type 0.005.

  6. In the Tolerance box, type 0.0001.

  7. Click OK to save these changes.

Figure 6.10. Achieve ECC = 0.005 Command Configuration

Achieve ECC = 0.005 Command Configuration

Run the Mission

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

Figure 6.11. 3D View of Hohmann Transfer

3D View of Hohmann Transfer

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

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

  2. Click Apply Corrections.

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

Chapter 7. Target Finite Burn to Raise Apogee

Audience

Intermediate level

Length

45 minutes

Prerequisites

Complete Simulating an Orbit and Simple Orbit Transfer

Script File

Tut_Target_Finite_Burn_to_Raise_Apogee.script

Objective and Overview

Note

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

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

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

The basic steps of this tutorial are:

  1. Create and configure the Spacecraft hardware and FiniteBurn resources

  2. Create the DifferentialCorrector and Target Control Variable

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

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

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

  4. Run the mission and analyze the results.

Create and Configure Spacecraft Hardware and Finite Burn

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

Create a Thruster and a Fuel Tank

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

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

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

  3. Double-click ChemicalThruster1 to edit its properties.

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

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

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

Figure 7.1. ChemicalTank1 Configuration

ChemicalTank1 Configuration

Figure 7.2. ChemicalThruster1 Configuration

ChemicalThruster1 Configuration

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

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

Modify Thruster1 Thrust Coefficients

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

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

Figure 7.3. ChemicalThruster1 Thrust Coefficients

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. In the Resources tree, double-click DefaultSC to edit its properties.

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

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

Figure 7.4. Attach ChemicalTank1 to DefaultSC

Attach ChemicalTank1 to DefaultSC

Figure 7.5. Attach ChemicalThruster1 to DefaultSC

Attach ChemicalThruster1 to DefaultSC

Create the Finite Burn Maneuver

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

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

  2. Double-click FiniteBurn1 to edit its properties.

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

Figure 7.6. Creation of FiniteBurn Resource FiniteBurn1

Creation of FiniteBurn Resource FiniteBurn1

Create the Differential Corrector and Target Control Variable

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

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

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

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

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

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

Figure 7.7. Creation of Variable Resource, BurnDuration

Creation of Variable Resource, BurnDuration

Configure the Mission Sequence

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

Configure the Initial Propagate Command

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

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

  3. Rename Propagate1 to Prop To Perigee.

Figure 7.8. Prop To Perigee Command Configuration

Prop To Perigee Command Configuration

Create the Target Sequence

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

Figure 7.9. Final Mission Sequence

Final Mission Sequence

To create the Target sequence:

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

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

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

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

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

Table 7.1. Additional Target Sequence Commands

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

Configure the Target Sequence

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

Configure the Raise Apogee Command

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

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

  3. Click OK to save these changes.

Figure 7.10. Raise Apogee Command Configuration

Raise Apogee Command Configuration

Configure the Vary Burn Duration Command

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

  2. In the Initial Value box, type 200

  3. In the Upper box, type 10000

  4. In the Max Step box, type 100.

  5. Click OK to save these changes.

Figure 7.11. Vary Burn Duration Command Configuration

Vary Burn Duration Command Configuration

Configure the Turn Thruster On Command

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

  2. Click OK.

Figure 7.12. Turn Thruster On Command Configuration

Turn Thruster On Command Configuration

Configure the Prop BurnDuration Command

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

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

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

  4. Click OK to save these changes.

Figure 7.13. Prop BurnDuration Command Configuration

Prop BurnDuration Command Configuration

Configure the Turn Thruster Off Command

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

  2. Click OK.

Figure 7.14. Turn Thruster Off Command Configuration

Turn Thruster Off Command Configuration

Configure the Prop To Apogee Command

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

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

  3. Click OK to save these changes.

Figure 7.15. Prop To Apogee Command Configuration

Prop To Apogee Command Configuration

Configure the Achieve Apogee Radius = 12000 Command

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

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

  3. In the Value box, type 12000

  4. Click OK to save these changes

Figure 7.16. Achieve Apogee Radius = 12000 Command Configuration

Achieve Apogee Radius = 12000 Command Configuration

Run the Mission

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

Inspect Orbit View and Message Window

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

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

3D View of Finite Burn to Raise Apogee

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

*** Targeting Completed in 13 iterations

      Final Variable values:

      BurnDuration = 1213.19316329

Explore the Command Summary Reports

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

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

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

  3. View the Turn Thruster Off command summary.

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

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

  4. View the Prop To Apogee command summary.

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

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

Chapter 8. Mars B-Plane Targeting

Audience

Advanced

Length

75 minutes

Prerequisites

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

Script File

Tut_Mars_B_Plane_Targeting.script

Objective and Overview

Note

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

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

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

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

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

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

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

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

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

  2. Create and configure a Fuel Tank resource.

  3. Create two ImpulsiveBurn resources with default settings.

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

  5. Create and configure DifferentialCorrector resource.

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

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

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

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

  10. Run the mission and analyze the results.

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

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

Create Fuel Tank

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

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

  2. Right-clickChemicalTank1 and click Rename.

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

  4. Double click onMainTank to edit its properties.

  5. Set the values shown in the table below.

    Table 8.1. MainTank settings

    FieldValue
    Fuel Mass1718
    Fuel Density1000
    Pressure5000
    Volume2


  6. Click OK to save these changes.

Modify the DefaultSC Resource

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

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

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

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

  4. Set the values shown in the table below.

    Table 8.2. MAVEN settings

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


  5. Click on Tanks tab now.

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

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

  8. Click OK to save these changes.

Create the Maneuvers

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

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

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

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

  4. Check Decrement Mass under Mass Change.

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

  6. Click OK to save these changes.

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

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

  9. Double-click MOI to edit its properties.

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

  11. Check Decrement Mass under Mass Change.

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

  13. Click OK to save these changes.

Create the Propagators

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

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

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

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

  4. Set the values shown in the table below.

    Table 8.3. NearEarth settings

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


  5. Click on OK to save these changes.

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

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

  8. Double-click DeepSpace to edit its properties.

  9. Set the values shown in the table below.

    Table 8.4. DeepSpace settings

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


  10. Click OK to save these changes.

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

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

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

  14. Set the values shown in the table below.

    Table 8.5. NearMars settings

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


  15. Click OK to save the changes.

Create the Differential Corrector

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

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

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

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

Create the Coordinate Systems

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

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

  2. Type SunEcliptic under Coordinate System Name box.

  3. Under Origin field, select Sun.

  4. For Type under Axes, select MJ2000Ec.

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

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

  7. Type MarsInertial under Coordinate System Name box.

  8. Under Origin field, select Mars.

  9. For Type under Axes, select BodyInertial.

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

Create the Orbit Views

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

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

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

  3. In the Output folder, delete DefaultGroundTrackPlot.

  4. Double-click EarthView to edit its properties.

  5. Set the values shown in the table below.

    Table 8.6. EarthView settings

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


  6. Click OK to save these changes.

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

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

  9. Double-click SolarSystemView to edit its properties.

  10. Set the values shown in the table below.

    Table 8.7. SolarSystemView settings

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


  11. Click OK to save these changes.

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

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

  14. Double-click MarsView to edit its properties.

  15. Set the values shown in the table below.

    Table 8.8. MarsView settings

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


  16. Click OK to save the changes.

Configure the Mission Sequence

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

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

Create the First Target Sequence

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

Figure 8.3. Mission Sequence for the First Target sequence

Mission Sequence for the First Target sequence

To create the first Target sequence:

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

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

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

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

  5. Right-click Target1 and click Rename.

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

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

  8. Right-click Propagate1 and click Rename.

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

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

    Table 8.9. Additional First Target Sequence Commands

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


Note

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

Configure the First Target Sequence

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

Configure the Target desired B-plane Coordinates Command

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

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

  3. Click OK to save these changes.

Figure 8.4. Target desired B-plane Coordinates Command Configuration

Target desired B-plane Coordinates Command Configuration

Configure the Prop 3 Days Command

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

  2. Under Propagator, make sure that NearEarth is selected

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

  4. Under Condition, replace 0.0 with 3.

  5. Click OK to save these changes.

Figure 8.5. Prop 3 Days Command Configuration

Prop 3 Days Command Configuration

Configure the Prop 12 Days to TCM Command

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

  2. Under Propagator, replace NearEarth with DeepSpace.

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

  4. Under Condition, replace 0.0 with 12.

  5. Click OK to save these changes.

Figure 8.6. Prop 12 Days to TCM Command Configuration

Prop 12 Days to TCM Command Configuration

Configure the Vary TCM.V Command

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

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

  3. In the Perturbation box, type 0.00001.

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

  5. In the Upper box, type 10e300.

  6. In the Max Step box, type 0.002.

  7. Click OK to save these changes.

Figure 8.7. Vary TCM.V Command Configuration

Vary TCM.V Command Configuration

Configure the Vary TCM.N Command

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

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

  3. Under Object List, click TCM.

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

  5. Click OK to close the ParameterSelectDialog window.

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

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

  8. In the Perturbation box, type 0.00001.

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

  10. In the Upper box, type 10e300.

  11. In the Max Step box, type 0.002.

  12. Click OK to save these changes.

Figure 8.8. Vary TCM.N Parameter Selection

Vary TCM.N Parameter Selection

Figure 8.9. Vary TCM.N Command Configuration

Vary TCM.N Command Configuration

Configure the Vary TCM.B Command

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

  2. Next to Variable, click the Edit button.

  3. Under Object List, click TCM.

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

  5. Click OK to close the ParameterSelectDialog window.

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

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

  8. In the Perturbation box, type 0.00001.

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

  10. In the Upper box, type 10e300.

  11. In the Max Step box, type 0.002.

  12. Click OK to save these changes.

Figure 8.10. Vary TCM.B Parameter Selection

Vary TCM.B Parameter Selection

Figure 8.11. Vary TCM.N Command Configuration

Vary TCM.N Command Configuration

Configure the Apply TCM Command

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

Figure 8.12. Apply TCM Command Configuration

Apply TCM Command Configuration

Configure the Prop 280 Days Command

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

  2. Under Propagator, replace NearEarth with DeepSpace.

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

  4. Under Condition, replace 0.0 with 280.

  5. Click OK to save these changes.

Figure 8.13. Prop 280 Days Command Configuration

Prop 280 Days Command Configuration

Configure the Prop to Mars Periapsis Command

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

  2. Under Propagator, replace NearEarth with NearMars.

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

  4. Click OK to save these changes.

Figure 8.14. Prop to Mars Periapsis Command Configuration

Prop to Mars Periapsis Command Configuration

Configure the Achieve BdotT Command

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

  2. Next to Goal, click the Edit button.

  3. In the Object Properties list, click BdotT.

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

  5. Click OK to close the ParameterSelectDialog window.

  6. In the Value box, type 0.

  7. In the Tolerance box, type 0.00001.

  8. Click OK to save these changes.

Figure 8.15. Achieve BdotT Command Configuration

Achieve BdotT Command Configuration

Configure the Achieve BdotR Command

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

  2. Next to Goal, click the Edit button.

  3. In the Object Properties list, click BdotR.

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

  5. Click OK to close the ParameterSelectDialog window.

  6. In the Value box, type -7000.

  7. In the Tolerance box, type 0.00001.

  8. Click OK to save these changes.

Figure 8.16. Achieve BdotR Command Configuration

Achieve BdotR Command Configuration

Run the Mission with first Target Sequence

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

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

3D View of departure hyperbolic trajectory (EarthView)

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

3D View of heliocentric transfer trajectory (SolarSystemView)

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

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

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

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

  2. Click Apply Corrections.

  3. Click OK to save these changes.

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

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

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

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

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

    Delta V Vector:

    Element 1: 0.0039376963731 km/s

    Element 2: 0.0060423170483 km/s

    Element 3: -0.0006747125434 km/s

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

    Delta V: 0.0072436375569 km/s

    Mass change: -6.3128738639690 kg

  4. Click OK to close Command Summary window.

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

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

  2. Under Coordinate System, select MarsInertial.

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

    BdotT = -0.0000053320678 km

    BdotR = -7000.0000019398 km

    INC = 90.000000039301 deg

Create the Second Target Sequence

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

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

Figure 8.20. Mission Sequence showing first and second Target sequences

Mission Sequence showing first and second Target sequences

To create the second Target sequence:

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

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

  3. Right-click Target2 and click Rename.

  4. Type Mars Capture and click OK.

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

  6. Right-click Vary4 and click Rename.

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

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

    Table 8.10. Additional Second Target Sequence Commands

    CommandName
    ManeuverApply MOI
    PropagateProp to Mars Apoapsis
    AchieveAchieve RMAG


Note

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

Create the Final Propagate Command

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

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

  2. Right-click Propagate6 and click Rename.

  3. Type Prop for 1 day and click OK.

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

  5. Under Propagator, replace NearEarth with NearMars.

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

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

  8. Click OK to save these changes

Figure 8.21. Prop for 1 day Command Configuration

Prop for 1 day Command Configuration

Configure the second Target Sequence

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

Configure the Mars Capture Command

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

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

  3. Click OK to save these changes

Figure 8.22. Mars Capture Command Configuration

Mars Capture Command Configuration

Configure the Vary MOI.V Command

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

  2. Next to Variable, click the Edit button.

  3. Under Object List, click MOI.

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

  5. Click OK to close the ParameterSelectDialog window.

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

  7. In the Perturbation box, type 0.00001.

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

  9. In the Upper box, type 10e300.

  10. In the Max Step box, type 0.1.

  11. Click OK to save these changes.

Figure 8.23. Vary MOI Parameter Selection

Vary MOI Parameter Selection

Figure 8.24. Vary MOI Command Configuration

Vary MOI Command Configuration

Configure the Apply MOI Command

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

  2. In the Burn list, click MOI.

  3. Click OK to save these changes.

Figure 8.25. Apply MOI Command Configuration

Apply MOI Command Configuration

Configure the Prop to Mars Apoapsis Command

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

  2. Under Propagator, replace NearEarth with NearMars.

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

  4. Click OK to save these changes.

Figure 8.26. Prop to Mars Apoapsis Command Configuration

Prop to Mars Apoapsis Command Configuration

Configure the Achieve RMAG Command

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

  2. Next to Goal, click the Edit button.

  3. In the Object Properties list, click RMAG.

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

  5. Click OK to close the ParameterSelectDialog window.

  6. In the Value box, type 12000.

  7. Click OK to save these changes.

Figure 8.27. Achieve RMAG Command Configuration

Achieve RMAG Command Configuration

Run the Mission with first and second Target Sequences

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

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

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

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

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

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

  2. Click Apply Corrections.

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

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

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

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

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

    Delta V Vector:

    Element 1: -1.6034665169868 km/s

    Element 2: 0.0000000000000 km/s

    Element 3: 0.0000000000000 km/s

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

    Delta V: 1.6034665169868 km/s

    Mass change: -1076.0639629424 kg

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

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

  2. Under Coordinate System, select MarsInertial.

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

    TA = 180.00000241484 deg

    RMAG = 12000.019889021 km

Chapter 9. Optimal Lunar Flyby using Multiple Shooting

Audience

Advanced

Length

90 minutes

Prerequisites

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

Script File

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

Objective and Overview

Note

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

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

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

  1. The spacecraft is at orbit perigee,

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

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

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

  1. The mission orbit perigee is 15 Earth radii.

  2. The mission orbit apogee is 60 Earth radii.

  3. The mission orbit inclination is 10 degrees.

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

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

View of Lunar Flyby from Normal to Earth Equator

Figure 9.2. View of Lunar Flyby Geometry

View of Lunar Flyby Geometry

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

Figure 9.3. Definition of Control and Patch Points

Definition of Control and Patch Points

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

  1. Create a Moon-centered coordinate system.

  2. Create 5 spacecraft required for modeling segments.

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

  4. Create an impulsive maneuver.

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

  6. Create A VF13ad optimizer.

  7. Create plots for tracking the optimization process.

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

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

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

  1. Run the sequence and analyze the initial guess.

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

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

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

  5. Apply an altitude constraint at lunar orbit periapsis

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

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

Create a Moon-centered Coordinate System

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

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

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

Create the Spacecraft

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

%----------------------------------------------------
% Configure spacecraft
%----------------------------------------------------

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

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

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

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

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

Create the Propagators

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

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

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

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

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

Create the Maneuvers

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

%----------------------------------------------------
% Configure maneuvers
%----------------------------------------------------

Create ImpulsiveBurn MOI
MOI.CoordinateSystem   = Local
MOI.Origin             = Earth
MOI.Axes               = VNB

Create the User Variables

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

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

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

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

%  Variables for managing time calculations
Create Variable patchTwoElapsedDays patchOneEpoch patchTwoEpoch refEpoch
Create Variable 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          = true
NLPOpt.ReportStyle           = Normal
NLPOpt.ReportFile            = 'VF13adVF13ad1.data'
NLPOpt.MaximumIterations     = 200
NLPOpt.Tolerance             = 1e-004
NLPOpt.UseCentralDifferences = false
NLPOpt.FeasibilityTolerance  = 0.1

Create the 3-D Graphics

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

%----------------------------------------------------
% 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 = All
PositionError.UpperLeft        = [ 0.02318840579710145 0.4358208955223881 ];
PositionError.Size             = [ 0.4594202898550724 0.5283582089552239 ];
PositionError.RelativeZOrder   = 378
PositionError.XVariable        = loopIdx
PositionError.YVariables       = {errorPos1, errorPos2}
PositionError.ShowGrid         = true
PositionError.ShowPlot         = true

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

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

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

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

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

Configure the Mission Sequence

Overview of the Mission Sequence

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

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

Define Initial Guesses

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

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

BeginMissionSequence

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

   %  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
   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 ...
   {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           = toiEpoch
   satMOI_Backward.Epoch.TAIModJulian  = moiEpoch
   satFlyBy_Forward.Epoch.TAIModJulian = flybyEpoch
   patchOneEpoch                       = refEpoch + patchOneElapsedDays
   patchTwoEpoch                       = refEpoch + patchTwoElapsedDays

Vary Control Point States

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

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

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

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

satFlyBy_Backward = satFlyBy_Forward

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

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

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 + ...
   (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
   If satMOI_Forward.Earth.TA > 180
     Propagate NearEarthProp(satMOI_Forward){satMOI_Forward.Earth.Periapsis}
   Else
      Propagate BackProp NearEarthProp(satMOI_Forward)...
      {satMOI_Forward.Earth.Periapsis}
   EndIf
   Maneuver MOI(satMOI_Forward)
   Propagate NearEarthProp(satMOI_Forward) {satMOI_Forward.Earth.Apoapsis}
   %NonlinearConstraint NLPOpt(satMOI_Forward.RadApo=conMOIApoapsis)
   errorMOIRadApo = satMOI_Forward.Earth.RadApo - conMOIApoapsis

Apply Cost Function

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

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

Design the Trajectory

Overview

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

  1. Run the script configuration and verify your configuration.

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

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

  4. Run the mission with an alternative initial guess.

  5. Add a new constraint and rerun the mission.

Step 1: Verify Your Configuration

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

Figure 9.4. View of Discontinuous Trajectory

View of Discontinuous Trajectory

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

Figure 9.5. Alternate View (1) of Discontinuous Trajectory

Alternate View (1) of Discontinuous Trajectory

Figure 9.6. Alternate View (2) of Discontinuous Trajectory

Alternate View (2) of Discontinuous Trajectory

Step 2: Find a Smooth Trajectory

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

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

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

  3. Click Save Sync Run.

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

Figure 9.7. Smooth Trajectory Solution

Smooth Trajectory Solution

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

Step 3: Find an Optimal Trajectory

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

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

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

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

Figure 9.8. Optimal Trajectory Solution

Optimal Trajectory Solution

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

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

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

Step 4: Use a New Initial Guess

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

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

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

Figure 9.9. Solution Using New Guess

Solution Using New Guess

Step 5: Apply a New Constraint

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

Chapter 10. Mars B-Plane Targeting Using GMAT Functions

Audience

Advanced

Length

75 minutes

Prerequisites

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

Script and function Files

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 10.1, “Geometry of the B-Plane as seen from a viewpoint perpendicular to the B-Plane” and Figure 10.2, “The B-vector as seen from a viewpoint perpendicular to orbit plane” show the geometry of the B-Plane and B-vector as seen from a viewpoint perpendicular to orbit plane. To read more on B-Planes, please consult the GMATMathSpec document. A good example involving the use of B-Plane targeting is a mission to Mars. Sending a spacecraft to Mars can be achieved by performing a Trajectory Correction Maneuver (TCM) that targets Mars B-Plane. Once the spacecraft gets close to Mars, then an orbit insertion maneuver can be performed to capture into Mars orbit.

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

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

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

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

In this tutorial, we will use GMAT to model a mission to Mars 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 Bi-normal (B) directions and includes four propagation sequences. The purpose of the maneuvers in VNB directions is to target BdotT and BdotR components of the B-vector. BdotT is targeted to 0 km and BdotR is targeted to a non-zero value to generate a polar orbit that has inclination of 90 degrees. BdotR is targeted to -7000 km to avoid having the orbit intersect Mars, which has a radius of approximately 3396 km. The 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 to assure continuous flow of data is plotted and reported to all the subscribers. The basic steps of this tutorial are:

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

  2. Create and configure a Fuel Tank resource.

  3. Create two ImpulsiveBurn resources with default settings.

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

  5. Create and configure DifferentialCorrector resource.

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

  7. Create and configure 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.

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

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

Create Fuel Tank

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

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

  2. Right-clickChemicalTank1 and click Rename.

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

  4. Double click onMainTank to edit its properties.

  5. Set the values shown in the table below.

    Table 10.1. MainTank settings

    FieldValue
    Fuel Mass1718
    Fuel Density1000
    Pressure5000
    Volume2


  6. Click OK to save these changes.

Modify the DefaultSC Resource

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

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

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

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

  4. Set the values shown in the table below.

    Table 10.2. MAVEN settings

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


  5. Click on Tanks tab now.

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

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

  8. Click OK to save these changes.

Create the Maneuvers

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

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

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

  3. Double-Click TCM to edit its properties.

  4. Check Decrement Mass under Mass Change.

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

  6. Click OK to save these changes.

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

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

  9. Double-click MOI to edit its properties.

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

  11. Check Decrement Mass under Mass Change.

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

  13. Click OK to save these changes.

Create the Propagators

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

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

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

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

  4. Set the values shown in the table below.

    Table 10.3. NearEarth settings

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


  5. Click on OK to save these changes.

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

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

  8. Double-click DeepSpace to edit its properties.

  9. Set the values shown in the table below.

    Table 10.4. DeepSpace settings

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


  10. Click OK to save these changes.

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

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

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

  14. Set the values shown in the table below.

    Table 10.5. NearMars settings

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


  15. Click OK to save the changes.

Create the Differential Corrector

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

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

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

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

Create the Coordinate Systems

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

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

  2. Type SunEcliptic under Coordinate System Name box.

  3. Under Origin field, select Sun.

  4. For Type under Axes, select MJ2000Ec.

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

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

  7. Type MarsInertial under Coordinate System Name box.

  8. Under Origin field, select Mars.

  9. For Type under Axes, select BodyInertial.

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

Create the Orbit Views

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

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

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

  3. In the Output folder, delete DefaultGroundTrackPlot.

  4. Double-click EarthView to edit its properties.

  5. Set the values shown in the table below.

    Table 10.6. EarthView settings

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


  6. Click OK to save these changes.

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

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

  9. Double-click SolarSystemView to edit its properties.

  10. Set the values shown in the table below.

    Table 10.7. SolarSystemView settings

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


  11. Click OK to save these changes.

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

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

  14. Double-click MarsView to edit its properties.

  15. Set the values shown in the table below.

    Table 10.8. MarsView settings

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


  16. Click OK to save the changes.

Create single Report File

We’ll need a single ReportFile resource for this tutorial that we'll use to report data to.

  1. Right-click the Output folder, point to Add, and click ReportFile. A new resource called ReportFile1 will be created.

  2. Rename the new ReportFile1 resource to rf and click OK.

  3. Double-Click rf to edit its properties.

  4. Empty the Parameter List by clicking on the Edit button.

  5. 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. Right-click the Functions folder, point to Add, point to GMAT Function and click New.

  2. A new GMAT function panel will open. Type the following name for the function TargeterInsideFunction and click OK to save these changes.

  3. Now open TargeterInsideFunction resource and paste the below shown first targeter sequence snippet into this function.

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

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

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 10.3, “Mission Sequence for the First Target sequence” illustrates the configuration of the Mission tree after you have completed the steps in this section.

Figure 10.3. Mission Sequence for the First Target sequence

Mission Sequence for the First Target sequence

Do following steps to set-up for the first Target sequence:

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

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

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

  4. Right-click on Mission Sequence folder, point to Append, and click Global. A new command called Global1 will be created.

  5. Right-click Global1 and click Rename. In the Rename box, type Make Objects Global and click OK.

  6. Right-click on Mission Sequence folder, point to Append, and click CallGmatFunction. A new command called CallGmatFunction1 will be created.

  7. Right-click CallGmatFunction1 and click Rename. In the Rename box, type Target Desired B-Plane Coord. From Inside Function and click OK.

  8. Right-click on Mission Sequence folder, point to Append, and click Report. A new command called Report1 will be created.

  9. 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. Double-click Make Objects Global to edit its properties.

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

  3. Click OK to save these changes.

Figure 10.4. Make Objects Global Command Configuration

Make Objects Global Command Configuration

Configure the Target Desired B-Plane Coord. From Inside Function Command

  1. Double-click Target Desired B-Plane Coord. From Inside Function to edit its properties.

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

  3. Click OK to save these changes.

Figure 10.5. Target Desired B-Plane Coord. From Inside Function Command Configuration

Target Desired B-Plane Coord. From Inside Function Command Configuration

Configure the Report Parameters Command

  1. Double-click Report Parameters to edit its properties.

  2. Under ReportFile, make sure rf is selected from the from drop down menu.

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

  4. Click OK to save these changes.

Figure 10.6. Report Parameters Command Configuration

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.

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

3D View of departure hyperbolic trajectory (EarthView)

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

3D View of heliocentric transfer trajectory (SolarSystemView)

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

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 10.10, “Mission Sequence showing first and second Target sequences” illustrates the configuration of the Mission tree after you have completed the steps in this section. Notice that in Figure 10.10, “Mission Sequence showing first and second Target sequences”, 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.

Figure 10.10. Mission Sequence showing first and second Target sequences

Mission Sequence showing first and second Target sequences

To create the second Target sequence:

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

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

  3. Right-click Target1 and click Rename.

  4. Type Mars Capture and click OK.

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

  6. Right-click Vary4 and click Rename.

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

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

    Table 10.9. Additional Second Target Sequence Commands

    CommandName
    ManeuverApply MOI
    PropagateProp to Mars Apoapsis
    AchieveAchieve RMAG


Note

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

Create the Final Propagate Command

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

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

  2. Right-click Propagate6 and click Rename.

  3. Type Prop for 1 day and click OK.

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

  5. Under Propagator, replace NearEarth with NearMars.

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

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

  8. Click OK to save these changes

Figure 10.11. Prop for 1 day Command Configuration

Prop for 1 day Command Configuration

Configure the second Target Sequence

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

Configure the Mars Capture Command

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

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

  3. Click OK to save these changes

Figure 10.12. Mars Capture Command Configuration

Mars Capture Command Configuration

Configure the Vary MOI.V Command

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

  2. Next to Variable, click the Edit button.

  3. Under Object List, click MOI.

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

  5. Click OK to close the ParameterSelectDialog window.

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

  7. In the Perturbation box, type 0.00001.

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

  9. In the Upper box, type 10e300.

  10. In the Max Step box, type 0.1.

  11. Click OK to save these changes.

Figure 10.13. Vary MOI Parameter Selection

Vary MOI Parameter Selection

Figure 10.14. Vary MOI Command Configuration

Vary MOI Command Configuration

Configure the Apply MOI Command

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

  2. In the Burn list, click MOI.

  3. Click OK to save these changes.

Figure 10.15. Apply MOI Command Configuration

Apply MOI Command Configuration

Configure the Prop to Mars Apoapsis Command

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

  2. Under Propagator, replace NearEarth with NearMars.

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

  4. Click OK to save these changes.

Figure 10.16. Prop to Mars Apoapsis Command Configuration

Prop to Mars Apoapsis Command Configuration

Configure the Achieve RMAG Command

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

  2. Next to Goal, click the Edit button.

  3. In the Object Properties list, click RMAG.

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

  5. Click OK to close the ParameterSelectDialog window.

  6. In the Value box, type 12000.

  7. Click OK to save these changes.

Figure 10.17. Achieve RMAG Command Configuration

Achieve RMAG Command Configuration

Run the Mission with first and second Target Sequences

Before running the mission, click Save (). This will save the additional changes that we implemented in the Mission tree. Now click Run (). The first Target sequence will converge 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.

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

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. In the Mission tree, right-click Apply MOI, and click on Command Summary.

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

    Delta V Vector:

    Element 1: -1.6032580309280 km/s

    Element 2: 0.0000000000000 km/s

    Element 3: 0.0000000000000 km/s

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

    Delta V: 1.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. In the Mission tree, right-click Achieve RMAG, and click on Command Summary.

  2. Under Coordinate System, select MarsInertial.

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

    TA = 180.00000085377 deg

    RMAG = 12000.017390989 km

Chapter 11. Finding Eclipses and Station Contacts

Audience

Beginner

Length

30 minutes

Prerequisites

Complete Simple Orbit Transfer

Script File

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. Load the Simple Orbit Transfer mission.

  2. Configure GMAT for event location.

  3. Add and configure an EclipseLocator to report eclipses.

  4. Run the mission and analyze the eclipse report.

  5. Add and configure a GroundStation and a ContactLocator to report contact times.

  6. 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. Open GMAT.

  2. Click Open in the toolbar and navigate to the GMAT samples directory.

  3. Select Tut_SimpleOrbitTransfer.script and click Open.

  4. Click Run () to run the mission.

You should see the following result in the DefaultOrbitView window.

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. On the Resources tab, double-click the SolarSystem folder. This will display the SolarSystem configuration.

  2. Scroll to the end of each input box to see the actual filenames being loaded.

You should see a configuration like this:

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. On the Resources tab, expand the SolarSystem folder.

  2. Double-click Earth to display the Earth configuration.

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

  4. Set Equatorial Radius to 6378.1366.

  5. Set Flattening to 0.00335281310845547.

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

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

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

  2. Click OK to accept the default settings. They are fine for our purposes.

The final configuration should match the following screenshot.

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:

    Finding events for EclipseLocator EclipseLocator1 ...
    Celestial body properties are provided by SPICE kernels.
  2. When the run is complete, click the Output tab to view the available output.

  3. Double-click EclipseLocator1 to view the eclipse report.

You'll see a report that looks similar to this:

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. First, close all graphics and solver windows, to allow full manipulation of resources.

  2. On the Resources tab, right-click the Ground Station folder and click Add Ground Station. This will create a new resource called GroundStation1.

  3. Rename GroundStation1 to Hyderabad.

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

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. On the Resources tab, right-click the Event Locators folder, point to Add, and click ContactLocator. This will create ContactLocator1.

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

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

  3. In the Observers list, enable Hyderabad. This will cause GMAT to search for contacts to this station.

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

  5. Click OK to accept the changes.

When fully configured, the GroundStation1 window will look like the following screenshot:

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:

    Finding events for ContactLocator ContactLocator1 ...
    Celestial body properties are provided by SPICE kernels.
  2. When the run is complete, click the Output tab to view the available output.

  3. Double-click ContactLocator1 to view the report.

You'll see a report that looks similar to this:

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.

Chapter 12. Electric Propulsion

Audience

Beginner

Length

15 minutes

Prerequisites

Complete Simulating an Orbit

Script File

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. Create and configure the Spacecraft hardware and FiniteBurn Resources

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

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

    2. Create a Propagate command to propagate while applying thrust from the electric propulsion system.

  3. Run the mission

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. In the Resources tree, right-click on the Hardware folder, point to Add, and click ElectricThruster.  A Resource named ElectricThruster1 will be created.

  2. In the Resources tree, right-click on the Hardware folder, point to Add, and click ElectricTank.  A Resource named ElectricTank1 will be created.

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

  2. In the Mass Change group box, check Decrement Mass.

  3. In the Mass Change group box, select ElectricTank1 for the Tank. 

  4. In the Thrust Config group box, select ConstantThrustAndIsp for ThrustModel and set ConstantThrust to 5.0 N. 

Figure 12.1, “ElectricThruster1 Configuration” below shows the ElectricThruster1 configuration that we will use.

Figure 12.1. ElectricThruster1 Configuration

ElectricThruster1 Configuration

We will use the default tank settings. Figure 12.2, “ElectricTank1 Configuration” shows the finished ElectricTank1 configuration.

Figure 12.2. ElectricTank1 Configuration

ElectricTank1 Configuration

  1. Double-click SolarPowerSystem1 to edit its properties.

  2. In the General group box, click the Select button next to ShadowBodies.

  3. Remove Earth from the ShadowBodies list. 

Figure 12.3, “SolarPowerSystem1 Configuration” shows the finished SolarPowerSystem1 configuration.

Figure 12.3. SolarPowerSystem1 Configuration

SolarPowerSystem1 Configuration

Attach Hardware to the Spacecraft

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

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

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

  4. Select the PowerSystem tab. In the PowerSystem tab, select SolarPowerSystem1. Click OK.

Figure 12.4. Attach ElectricTank1 to DefaultSC

Attach ElectricTank1 to DefaultSC

Figure 12.5. Attach ElectricThruster1 to DefaultSC

Attach ElectricThruster1 to DefaultSC

Figure 12.6. Attach SolarPowerSystem1 to DefaultSC

Attach SolarPowerSystem1 to DefaultSC

Create the Finite Burn Maneuver

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

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

  2. Double-click FiniteBurn1 to edit its properties.

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

Figure 12.7. Creation of FiniteBurn Resource FiniteBurn1

Creation of FiniteBurn Resource FiniteBurn1

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 12.8. Final Mission Sequence

Final Mission Sequence

Create the Commands

  1. In the Mission Tree, right click on Propagate1, select Rename, and enter Propagate Two Days.

  2. Right click on the command named Propagate Two Days, select Insert Before, then select BeginFiniteBurn.

  3. Right click on the command named Propagate Two Days, select Insert After, then select EndFiniteBurn.

  4. Rename the command named BeginFiniteBurn1 to StartTheManeuver.

  5. 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 12.9. Prop To Perigee Command Configuration

Prop To Perigee 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 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 12.10. 3D View of Finite Electric Maneuver

3D View of Finite Electric Maneuver

Chapter 13. Simulate DSN Range and Doppler Data

Audience

Intermediate level

Length

40 minutes

Prerequisites

Basic Mission Design Tutorials

Script Files

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. Create and configure the spacecraft, spacecraft transponder, and related parameters

  2. Create and configure the Ground Station and related parameters

  3. Define the types of measurements to be simulated

  4. Create and configure Force model and propagator

  5. Create and configure Simulator object

  6. Run the mission and analyze the results

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

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       = UTCGregorian;
Sat.CoordinateSystem = SunMJ2000Eq;
Sat.DisplayStateType = Cartesian;
Sat.Epoch            = 19 Aug 2015 00:00:00.000;
Sat.X                = -126544968
Sat.Y                =  61978514
Sat.Z                =  24133221
Sat.VX               = -13.789
Sat.VY               = -24.673
Sat.VZ               = -10.662

Sat.Id               = 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                    = {SatTransponder, HGA};

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     = DSNAntenna;
DSNReceiver.PrimaryAntenna        = DSNAntenna;
DSNTransmitter.Frequency          = 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
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       = 'IRI2007';
CAN.TroposphereModel      = '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                = 'Doppler_HZ';
DSNdoppler.NoiseSigma          = 0.0282;
DSNdoppler.Bias                = 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 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               = true;
DSNsimData.UseRelativityCorrection  = true;
DSNsimData.UseETminusTAI            = true;

DSNsimData.SimDopplerCountInterval  = 10.0;
DSNsimData.SimRangeModuloConstant   = 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 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            = Sun;
Fm.PointMasses            = {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             = {DSNsimData};
Sim.EpochFormat         = UTCGregorian;
Sim.InitialEpoch        = '19 Aug 2015 00:00:00.000';
Sim.FinalEpoch          = '19 Aug 2015 00:12:00.000';
Sim.MeasurementTimeStep = 600;
Sim.Propagator          = Prop;
Sim.AddNoise            = 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 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 
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 X-band 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.

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;
GDS.Location3             = 3677.052370;
GDS.Id                    = '33333';
GDS.AddHardware           = {DSNTransmitter, DSNAntenna, DSNReceiver};
GDS.MinimumElevationAngle = 7.0;
GDS.IonosphereModel       = 'IRI2007';
GDS.TroposphereModel      = 'HopfieldSaastamoinen';

Create GroundStation MAD;  
MAD.CentralBody           = Earth;
MAD.StateType             = Cartesian;
MAD.HorizonReference      = Ellipsoid;
MAD.Location1             = 4849.519988;
MAD.Location2             = -0360.641653;
MAD.Location3             = 4114.504590;
MAD.Id                    = '44444';
MAD.AddHardware           = {DSNTransmitter, DSNAntenna, DSNReceiver};
MAD.MinimumElevationAngle = 7.0;
MAD.IonosphereModel       = 'IRI2007';
MAD.TroposphereModel      = '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           = {DSNrange, DSNdoppler};
MAD.ErrorModels           = {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 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.

f ( t ) = f ( t o ) + R a m p R a t e * 86400 * ( t t o )

where

f ( t o ) = Transmit Frequency at the start of the ramp record
f ( t ) = Transmit Frequency at a later time,  t > t o

Note that, in the typical case where there are numerous ramp records, it is assumed that t o < t is chosen as close to time t as possible. For our case above, the transmit frequency from CAN to Sat at time t is

f ( t ) = 7.2 e 9 + 0.2 * 86400 * ( 27252.5 27252 ) = 7200008640 Hz

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. 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]):

C t 1 t 3 f T ( t ) d t ,  mod M             (RU)

where

t 1 , t 3 = Transmission and Reception epoch, respectively
f T = Ground Station transmit frequency
C = transmitter dependent constant (221/1498 for X-band and 1/2 for S-Band)
=  length of the ranging code in RU

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.

C d ( in meters ) c f ¯ T =  d(in RU)

where

f ¯ T =   t 1 t 3 f T ( t ) d t ( t 3 t 1 ) = average transmit frequency (between transmit and receive),
c=speed of light in m/s
d= round trip distance

If we assume the round trip distance is 1 meter, we have

d(in RU) = C f ¯ T c

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, f ¯ T = f T , and thus

d(in RU)=  221 1498 7200 e 6 299792458   = 3 .543172 RU

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.

   O  [ ϕ ( t 3 e ) ϕ ( t 3 s ) ] t 3 e t 3 s   (Hz)

where

t 1 s , t 1 e = start and end of transmission interval
t 3 s , t 3 e = start and end of reception interval
ϕ = Total Count Phase (type 17 Trk 2-34 record)

In the absence of measurement noise, one can show (Moyer [2000]), that the Observed value (O) above equals the Computed (C) value below.

  C = M 2 ( t 3 e t 3 s ) t 1 s t 1 e f T ( t 1 ) d t 1   = M 2 ( t 1 e t 1 s ) D C I f ¯ T     (Hz)

where

t 1 s , t 1 e = start and end of transmission interval
f T = transmit frequency
M 2 = Transponder turn around ratio (typically, 240/221 for S-band and 880/749 for X-band)
DCI =  ( t 3 e t 3 s ) =  Doppler Count Interval
f ¯ T t 1 s t 1 e f T ( t 1 ) d t 1 ( t 1 e t 1 s )   = average transmit frequency 

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.

ρ ˙ ¯ O b s e r v e d = c ( 1 + O M 2 f ¯ T ) ,   ρ ˙ ¯ C o m p u t e d = c ( 1 + C M 2 f ¯ T )

where

ρ ˙ ¯ ( Round Trip distance at  t 3 e ) ( Round Trip distance at  t 3 s ) t 3 e t 3 s

Thus, we determine that

ρ ˙ ¯ O b s e r v e d ρ ˙ ¯ C o m p u t e d = c M 2 f ¯ T ( O C )

The quantity, ( O C ) , 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 M 2 f ¯ T c = M 2 f ¯ T 299792458000 . In our case, where we use a constant X-band frequency of 7.2e9, the conversion factor is given by 880 749 7.2 e 9 299792458000 0 .0282 . 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.

Chapter 14. Orbit Estimation using DSN Range and Doppler Data

Audience

Intermediate level

Length

60 minutes

Prerequisites

Simulate DSN Range and Doppler Data Tutorial

Script Files

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. Create and configure the spacecraft, spacecraft transponder, and related parameters

  2. Create and configure the Ground Station and related parameters

  3. Define the types of measurements to be processed

  4. Create and configure Force model and propagator

  5. Create and configure Batch Estimator object

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

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       = UTCGregorian;
Sat.CoordinateSystem = SunMJ2000Eq;
Sat.DisplayStateType = Cartesian;
Sat.Epoch            = 19 Aug 2015 00:00:00.000;
Sat.X                = -126544963   %-126544968
Sat.Y                = 61978518     %61978514
Sat.Z                = 24133225     %24133221
Sat.VX               = -13.789
Sat.VY               = -24.673
Sat.VZ               = -10.662

Sat.Id               = 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;  %High Gain Antenna

Create Transponder SatTransponder;
SatTransponder.PrimaryAntenna   = HGA;
SatTransponder.HardwareDelay    = 1e-06; %seconds
SatTransponder.TurnAroundRatio  = '880/749';

Sat.AddHardware                 = {SatTransponder, HGA};
Sat.SolveFors                   = {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     = DSNAntenna;
DSNReceiver.PrimaryAntenna        = DSNAntenna;
DSNTransmitter.Frequency          = 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 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 and associated error models
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       = 'IRI2007';
CAN.TroposphereModel      = '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.

%   Create GDS transmitter and ground station 
Create Transmitter GDSTransmitter
GDSTransmitter.Frequency      = 7300;   %MHz.
GDSTransmitter.PrimaryAntenna = DSNAntenna;

Create GroundStation GDS;  
GDS.CentralBody               = Earth;
GDS.StateType                 = Cartesian;
GDS.HorizonReference          = Ellipsoid;
GDS.Location1                 = -2353.621251;
GDS.Location2                 = -4641.341542;
GDS.Location3                 = 3677.052370;
GDS.Id                        = '33333';
GDS.AddHardware               = {GDSTransmitter, ...
                                 DSNAntenna, DSNReceiver};
GDS.MinimumElevationAngle     = 7.0;
GDS.IonosphereModel           = '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               = Earth;
MAD.StateType                 = Cartesian;
MAD.HorizonReference          = Ellipsoid;
MAD.Location1                 = 4849.519988;
MAD.Location2                 = -360.641653;
MAD.Location3                 = 4114.504590;
MAD.Id                        = '44444';
MAD.AddHardware               = {MADTransmitter, ...
                                  DSNAntenna, DSNReceiver};
MAD.MinimumElevationAngle     = 7.0;
MAD.IonosphereModel           = '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 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 models
Create ErrorModel DSNrange;
DSNrange.Type                   = 'Range_RU';
DSNrange.NoiseSigma             = 10.63;
DSNrange.Bias                   = 0.0;

Create ErrorModel DSNdoppler;
DSNdoppler.Type                 = 'Doppler_HZ';
DSNdoppler.NoiseSigma           = 0.0282;
DSNdoppler.Bias                 = 0.0;

CAN.ErrorModels                 = {DSNrange, DSNdoppler};
GDS.ErrorModels                 = {DSNrange, DSNdoppler};
MAD.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 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         = {{CAN, Sat, CAN}, 'DSNRange'};   
DSNsimData.AddTrackingConfig         = {{CAN, Sat, CAN}, 'Doppler'};                 
DSNsimData.AddTrackingConfig         = {{GDS, Sat, GDS}, 'DSNRange'};   
DSNsimData.AddTrackingConfig         = {{GDS, Sat, GDS}, 'Doppler'};                 
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              = true;
DSNsimData.UseRelativityCorrection   = true;
DSNsimData.UseETminusTAI             = 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             = Sun;
Fm.PointMasses             = {Sun, Earth, Luna, Mars, Saturn, ...
                             Uranus, Mercury, Venus, Jupiter};
Fm.SRP                     = On;
Fm.RelativisticCorrection  = On;
Prop.FM                    = Fm;
Prop.MinStep               = 0;
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 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.

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.

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.

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

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 
	  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.044634165793e+001        3.112863356104e+000       -2.345908150453e-006        5.035500518048e-007        1.602400702334e-006
        1.044634082751e+001        2.043155461343e+001       -4.258301029878e+000       -3.704075903144e-006        2.022938490903e-007        3.971535902921e-006
        3.112865361595e+000       -4.258297445960e+000        2.371732979013e+001       -1.178974996784e-006        1.683977194948e-006       -2.674173473312e-006
       -2.345908159193e-006       -3.704076213842e-006       -1.178974284159e-006        8.386165742100e-013       -1.658563839962e-013       -6.047842793431e-013
        5.035500497713e-007        2.022939026968e-007        1.683977056710e-006       -1.658563826712e-013        1.032575255469e-012       -2.190676053421e-012
        1.602400700119e-006        3.971536117909e-006       -2.674174002075e-006       -6.047842762516e-013       -2.190676053038e-012        5.776276322091e-012

Final Correlation Matrix:

             1.000000000000             0.901851016006             0.249429858518            -0.999655967713             0.193376220513             0.260176714954
             0.901850944314             1.000000000000            -0.193442883328            -0.894844247176             0.044042413976             0.365581159741
             0.249430019216            -0.193442720520             1.000000000000            -0.264356490609             0.340284723675            -0.228471850851
            -0.999655971438            -0.894844322236            -0.264356330820             1.000000000000            -0.178233614796            -0.274786120507
             0.193376219732             0.044042425647             0.340284695741            -0.178233613372             1.000000000000            -0.897001819395
             0.260176714594             0.365581179531            -0.228471896026            -0.274786119102            -0.897001819239             1.000000000000

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

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 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 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            Size             Bytes  Class     Attributes

  Iteration0      1x1             847660  struct              
  Iteration1      1x1             847690  struct              
  Iteration2      1x1             847696  struct             

You may see more or fewer iterations depending on your run. Each iteration variable is a structure containing the following arrays:

StatusObservation status flag, 1 = observation is good/useable
IterationNumberThe iteration number. This matches the iteration number in the structure name.
EpochThe TAIModJulian time tag of each observation, computed value, and residual
ObservedThe observed value (from the GMD file) in Range Units or Hertz
CalculatedThe predicted observation, in Range Units or Hertz, computed by GMAT using the force modeling specified in the batch estimator propagator
ObsMinusCalculatedThe observation residual, in Range Units or Hertz
ElevationThe computed elevation of the observation, in degrees
FrequencyThe transmit frequency at the time of the observation, in Hertz
FrequencyBandThe frequency band of the observation. See the TrackingFileSet help for a list of frequency band indicators.
DopplerCountIntervalThe Doppler count interval in seconds, for Doppler observations. Set to -1 for range observations.
ParticipantsFor each observation, a comma-separated string identifying the transmit station, tracked object, and receive station in order
TypeA string identifying the observation type, DSNRange or Doppler
UTCGregorianThe UTCGregorian epoch string of each observation
ObsEditFlagThe 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]Goddard Trajectory Mathematical Theory, Revision 1, Edited by A. Long, J. Cappellari, et al., Computer Sciences Corporation, FDD, FDD-552-89-0001, July 1989.
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 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}


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

   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:

   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.044634165793e+001        3.112863356104e+000       -2.345908150453e-006        5.035500518048e-007        1.602400702334e-006
        1.044634082751e+001        2.043155461343e+001       -4.258301029878e+000       -3.704075903144e-006        2.022938490903e-007        3.971535902921e-006
        3.112865361595e+000       -4.258297445960e+000        2.371732979013e+001       -1.178974996784e-006        1.683977194948e-006       -2.674173473312e-006
       -2.345908159193e-006       -3.704076213842e-006       -1.178974284159e-006        8.386165742100e-013       -1.658563839962e-013       -6.047842793431e-013
        5.035500497713e-007        2.022939026968e-007        1.683977056710e-006       -1.658563826712e-013        1.032575255469e-012       -2.190676053421e-012
        1.602400700119e-006        3.971536117909e-006       -2.674174002075e-006       -6.047842762516e-013       -2.190676053038e-012        5.776276322091e-012

Final Correlation Matrix:

             1.000000000000             0.901851016006             0.249429858518            -0.999655967713             0.193376220513             0.260176714954
             0.901850944314             1.000000000000            -0.193442883328            -0.894844247176             0.044042413976             0.365581159741
             0.249430019216            -0.193442720520             1.000000000000            -0.264356490609             0.340284723675            -0.228471850851
            -0.999655971438            -0.894844322236            -0.264356330820             1.000000000000            -0.178233614796            -0.274786120507
             0.193376219732             0.044042425647             0.340284695741            -0.178233613372             1.000000000000            -0.897001819395
             0.260176714594             0.365581179531            -0.228471896026            -0.274786119102            -0.897001819239             1.000000000000

********************************************************


Mission run completed.
===> Total Run Time: 85.739000 seconds

========================================

Appendix B – Zeroth Iteration Plots of Observation Residuals

Appendix C – First Iteration Plots of Observation Residuals

Reference Guide

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

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

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

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

Table of Contents

I. Resources
Antenna — Transmits or receives an RF signal.
Array — A user-defined one- or two-dimensional array variable
Barycenter — The center of mass of selected celestial bodies
BatchEstimatorInv — A batch least squares estimator
CelestialBody — A celestial body model
CoordinateSystem — An axis and origin pair
ContactLocator — A line-of-sight event locator between a target Spacecraft and an observer GroundStation
DifferentialCorrector — A numerical solver
ElectricTank — A model of a tank containing fuel for an electric propulsion system
ElectricThruster — An electric thruster model
EclipseLocator — A Spacecraft eclipse event locator
EphemerisFile — Generate spacecraft’s ephemeris data
ErrorModel — Used to specify measurement noise for simulation and estimation, and to apply or estimate measurement biases.
FileInterface — An interface to a data file
FiniteBurn — A finite burn
FminconOptimizer — The Sequential Quadratic Programming (SQP) optimizer, fmincon
Formation — A collection of spacecraft.
ChemicalTank — Model of a chemical fuel tank
GMATFunction — Declaration of a GMAT function
GroundStation — A ground station model.
GroundTrackPlot — A user-defined resource that draws longitude and latitude time-history of a spacecraft
ImpulsiveBurn — An impulsive maneuver
LibrationPoint — An equilibrium point in the circular, restricted 3-body problem
MatlabFunction — Declaration of an external MATLAB function
NuclearPowerSystem — A nuclear power system
OrbitView — A user-defined resource that plots 3-Dimensional trajectories
Propagator — A propagator models spacecraft motion
Receiver — Hardware that receives an RF signal.
ReportFile — Report data to a text file
Simulator — Configures the generation of simulated tracking data measurements.
SNOPT — The Sequential Quadratic Programming (SQP) optimizer, SNOPT
SolarPowerSystem — A solar power system model
SolarSystem — High level solar system configuration options
Spacecraft — A spacecraft model
Spacecraft Attitude — The spacecraft attitude model
Spacecraft Ballistic/Mass Properties — The physical properties of the spacecraft
Spacecraft Epoch — The spacecraft epoch
Spacecraft Hardware — Add hardware to a spacecraft
Spacecraft Navigation — There are a number of Spacecraft fields that are used exclusively to support GMAT's navigation capability.
Spacecraft Orbit State — The orbital initial conditions
Spacecraft Visualization Properties — The visual properties of the spacecraft
StatisticsAcceptFilter — Allows selection of data subsets for processing by the batch least squares estimator.
StatisticsRejectFilter — Allows selection of data subsets for processing by the batch least squares estimator.
String — A user-defined string variable
TrackingFileSet — Manages the observation data contained in one or more external tracking data files.
Transmitter — Defines the electronics hardware, attached to a GroundStation resource, that transmits an RF signal.
Transponder — Defines the electronics hardware, typically attached to a spacecraft, that receives and automatically re-transmits an incoming signal.
ChemicalThruster — A chemical thruster model
Variable — A user-defined numeric variable
VF13ad — The Sequential Quadratic Programming (SQP) optimizer, VF13ad
XYPlot — Plots data onto the X and Y axes of a graph
II. Commands
Achieve — Specify a goal for a Target sequence
Assignment (=) — Set a variable or resource field to a value, possibly using mathematical expressions
BeginFiniteBurn — Model finite thrust maneuvers
BeginMissionSequence — Begin the mission sequence portion of a script
BeginScript — Execute free-form script commands
CallGmatFunction — Call a GMAT function
CallMatlabFunction — Call a MATLAB function
CallPythonFunction — Call a Python function
ClearPlot — Allows you to clear all data from an XYPlot
EndFiniteBurn — Model finite thrust maneuvers in the mission sequence
FindEvents — Execute an event location search
For — Execute a series of commands a specified number of times
GetEphemStates() — Function used to output initial and final spacecraft states from an ephemeris file
Global — Declare Objects as global
If — Conditionally execute a series of commands
Maneuver — Perform an impulsive (instantaneous) maneuver
MarkPoint — Allows you to add a special mark point character on an XYPlot
Minimize — Define the cost function to minimize
NonlinearConstraint — Specify a constraint used during optimization
Optimize — Solve for condition(s) by varying one or more parameters
PenUpPenDown — Allows you to stop or begin drawing data on a plot
Propagate — Propagates spacecraft to a requested stopping condition
Report — Allows you to write data to a text file
RunEstimator — Ingests navigation measurements and generates an estimated state vector
RunSimulator — Generates simulated navigation measurements
Set — Configure a resource from a data interface
Stop — Stop mission execution
Target — Solve for condition(s) by varying one or more parameters
Toggle — Allows you to turn data output off or on
Vary — Specifies variables used by a solver
While — Execute a series of commands repeatedly while a condition is met
Write — Writes data to one or more of the following three destinations: the message window, the log file, or a ReportFile resource.
III. System
Calculation Parameters — Resource properties available for use by commands and output
Color — Color support in GMAT resources and commands
Command-Line Usage — Starting the GMAT application from the command line
#Include Macro — Load or import a script snippet
Keyboard Shortcuts — Keyboard shortcuts in the graphical user interface
MATLAB Interface — Interface to MATLAB system
Python Interface — Interface to the Python programming language
Script Language — The GMAT script language
Startup File — The gmat_startup_file.txt configuration file

Resources


Table of Contents

Antenna — Transmits or receives an RF signal.
Array — A user-defined one- or two-dimensional array variable
Barycenter — The center of mass of selected celestial bodies
BatchEstimatorInv — A batch least squares estimator
CelestialBody — A celestial body model
CoordinateSystem — An axis and origin pair
ContactLocator — A line-of-sight event locator between a target Spacecraft and an observer GroundStation
DifferentialCorrector — A numerical solver
ElectricTank — A model of a tank containing fuel for an electric propulsion system
ElectricThruster — An electric thruster model
EclipseLocator — A Spacecraft eclipse event locator
EphemerisFile — Generate spacecraft’s ephemeris data
ErrorModel — Used to specify measurement noise for simulation and estimation, and to apply or estimate measurement biases.
FileInterface — An interface to a data file
FiniteBurn — A finite burn
FminconOptimizer — The Sequential Quadratic Programming (SQP) optimizer, fmincon
Formation — A collection of spacecraft.
ChemicalTank — Model of a chemical fuel tank
GMATFunction — Declaration of a GMAT function
GroundStation — A ground station model.
GroundTrackPlot — A user-defined resource that draws longitude and latitude time-history of a spacecraft
ImpulsiveBurn — An impulsive maneuver
LibrationPoint — An equilibrium point in the circular, restricted 3-body problem
MatlabFunction — Declaration of an external MATLAB function
NuclearPowerSystem — A nuclear power system
OrbitView — A user-defined resource that plots 3-Dimensional trajectories
Propagator — A propagator models spacecraft motion
Receiver — Hardware that receives an RF signal.
ReportFile — Report data to a text file
Simulator — Configures the generation of simulated tracking data measurements.
SNOPT — The Sequential Quadratic Programming (SQP) optimizer, SNOPT
SolarPowerSystem — A solar power system model
SolarSystem — High level solar system configuration options
Spacecraft — A spacecraft model
Spacecraft Attitude — The spacecraft attitude model
Spacecraft Ballistic/Mass Properties — The physical properties of the spacecraft
Spacecraft Epoch — The spacecraft epoch
Spacecraft Hardware — Add hardware to a spacecraft
Spacecraft Navigation — There are a number of Spacecraft fields that are used exclusively to support GMAT's navigation capability.
Spacecraft Orbit State — The orbital initial conditions
Spacecraft Visualization Properties — The visual properties of the spacecraft
StatisticsAcceptFilter — Allows selection of data subsets for processing by the batch least squares estimator.
StatisticsRejectFilter — Allows selection of data subsets for processing by the batch least squares estimator.
String — A user-defined string variable
TrackingFileSet — Manages the observation data contained in one or more external tracking data files.
Transmitter — Defines the electronics hardware, attached to a GroundStation resource, that transmits an RF signal.
Transponder — Defines the electronics hardware, typically attached to a spacecraft, that receives and automatically re-transmits an incoming signal.
ChemicalThruster — A chemical thruster model
Variable — A user-defined numeric variable
VF13ad — The Sequential Quadratic Programming (SQP) optimizer, VF13ad
XYPlot — Plots data onto the X and Y axes of a graph

Antenna

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;

Create GroundStation DSN;
DSN.AddHardware                   = ...
                       {DSNTransmitter, DSNReceiver, GenericAntenna};
BeginMissionSequence;

Array

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

Description

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

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

Create Array anArray[rows, columns]

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

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

anArray(row, column) = value

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

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

anArray = array expression

See Also: String, Variable

Fields

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

FieldDescription
rows

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

Data Type

Integer

Allowed Values

1 ≤ rows ≤ 1000

Access

set

Default Value

1

Units

N/A

Interfaces

GUI, script

columns

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

Data Type

Integer

Allowed Values

1 ≤ columns ≤ 1000

Access

set

Default Value

1

Units

N/A

Interfaces

GUI, script

value

The value of the array element being addressed.

Data Type

Real number

Allowed Values

-∞ < value < ∞

Access

set, get

Default Value

0.0

Units

N/A

Interfaces

GUI, script

GUI

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

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

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

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

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

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

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

  • Click a cell once to select it

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

  • Use the arrow keys to select adjacent cells

  • Click the corner header cell to select the entire table

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

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

Remarks

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

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

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

Examples

Creating and reporting an array:

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

BeginMissionSequence

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

Barycenter

Barycenter — The center of mass of selected celestial bodies

Description

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

See Also: LibrationPoint, CoordinateSystem, CelestialBody, SolarSystem, Color

Fields

FieldDescription
BodyNames

The list of CelestialBody resources included in the Barycenter. Providing empty brackets sets the bodies to the default list described below.

Data Type

String array

Allowed Values

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

Access

set

Default Value

Earth, Luna

Units

N/A

Interfaces

GUI, script

OrbitColor

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

Integer Array or String

Allowed Values

Any color available from the Orbit Color Picker in GUI. Valid predefined color name or RGB triplet value between 0 and 255.

Access

set

Default Value

Gold

Units

N/A

Interfaces

GUI, script

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

Integer Array or String

Allowed Values

Any color available from the Orbit Color Picker in GUI. Valid predefined color name or RGB triplet value between 0 and 255.

Access

set

Default Value

DarkGray

Units

N/A

Interfaces

GUI, script

GUI

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

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

Remarks

Built-in SolarSystemBarycenter Object

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

Custom Barycenter Objects

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

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 

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 

BatchEstimatorInv

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

FieldDescription
AbsoluteTol

Absolute Weighted RMS convergence criteria tolerance

Data Type

Real

Allowed Values

Real > 0

Access

set

Default Value

0.001

Units

dimensionless

Interfaces

script

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

String

Allowed Values

'FromParticipants'

Access

set

Default Value

'FromParticipants'

Units

N/A

Interfaces

script

EstimationEpochFormat

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

String

Allowed Values

'FromParticipants'

Access

set

Default Value

'FromParticipants'

Units

N/A

Interfaces

script

InverseAlgorithm

Algorithm used to invert the normal equations

Data Type

String

Allowed Values

Internal, Cholesky, Schur

Access

set

Default Value

Internal

Units

N/A

Interfaces

script

MatlabFile

File name for the output MATLAB file. A value of None means that no MATLAB file will be output.

Data Type

String

Allowed Values

Any valid file name.

Access

set

Default Value

None

Units

N/A

Interfaces

script

MaxConsecutiveDivergences

Specifies maximum number of consecutive diverging iterations allowed before batch estimation processing is stopped

Data Type

integer

Allowed Values

any positive integer

Access

set

Default Value

3

Units

N/A

Interfaces

script

MaximumIterations

Specifies maximum number of iterations allowed for batch estimation

Data Type

integer

Allowed Values

any positive integer

Access

set

Default Value

15

Units

N/A

Interfaces

script

Measurements

Specifies a list of measurements used for batch estimation

Data Type

ObjectArray

Allowed Values

valid TrackingFileSet object

Access

set

Default Value

empty list

Units

N/A

Interfaces

script

OLSEAdditiveConstant

Additive constant used for outer loop sigma editing (OLSE)

Data Type

Real

Allowed Values

any real number

Access

set

Default Value

0.0

Units

dimensionless

Interfaces

script

OLSEInitialRMSSigma

Initial predicted root-mean-square value used for outer loop sigma editing (OLSE)

Data Type

Real

Allowed Values

Real > 0.0

Access

set

Default Value

3000.0

Units

dimensionless

Interfaces

script

OLSEMultiplicativeConstant

Multiplicative constant used for outer loop sigma editing (OLSE)

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

Object

Allowed Values

valid Propagator object

Access

set

Default Value

None

Units

N/A

Interfaces

script

RelativeTol

Relative Weighted RMS convergence criteria tolerance

Data Type

Real

Allowed Values

Real > 0

Access

set

Default Value

0.0001

Units

dimensionless

Interfaces

script

ReportFile

Specifies the name of estimation report file

Data Type

String

Allowed Values

string containing a valid file name

Access

set

Default Value

'BatchEstimatorInv' + instancename + '.data'

Units

N/A

Interfaces

script

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

String

Allowed Values

Normal

Access

set

Default Value

Normal

Units

N/A

Interfaces

script

ResetBestRMSIfDiverging

If set true and the estimation process has diverged, then the Best RMS is reset to the current RMS.

Data Type

true/false

Allowed Values

true or false

Access

set

Default Value

false

Units

N/A

Interfaces

script

ShowAllResiduals

Allows residuals plots to be shown

Data Type

On/Off

Allowed Values

On or Off

Access

set

Default Value

On

Units

N/A

Interfaces

script

ShowProgress

Allows detailed output of the batch estimator to be shown in the message window

Data Type

true/false

Allowed Values

true or false

Access

set

Default Value

true

Units

N/A

Interfaces

script

UseInitialCovariance

If set true, a priori error covariance term is added to the estimation cost function.

Data Type

true/false

Allowed Values

true or false

Access

set

Default Value

false

Units

N/A

Interfaces

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

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

ResourceDescription
TrackingFileSet resource

Must be created in order to tell the BatchEstimatorInv resource which data will be processed

Propagator resourceUsed by GMAT to generate the predicted orbit
RunEstimator command

Must use the RunEstimator command to actually process the data defined by the BatchEstimatorInv resource

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               = true;
bat.Measurements               = {estData} 
bat.AbsoluteTol                = 0.000001;
bat.RelativeTol                = 0.001;
bat.MaximumIterations          = 10;
bat.MaxConsecutiveDivergences  = 3;
bat.Propagator                 = ODProp;
bat.ShowAllResiduals           = On;
bat.OLSEInitialRMSSigma        = 3000;
bat.OLSEMultiplicativeConstant = 3;
bat.OLSEAdditiveConstant       = 0;
bat.InversionAlgorithm         = 'Internal';
bat.EstimationEpochFormat      = 'FromParticipants';
bat.EstimationEpoch            = 'FromParticipants'; 
bat.ReportStyle                = 'Normal';
bat.ReportFile                 = 'BatchEstimator_Report.txt';

BeginMissionSequence;

For a comprehensive example of reading in measurements and running the estimator, see the Chapter 14, Orbit Estimation using DSN Range and Doppler Data tutorial.


CelestialBody

CelestialBody — A celestial body model

Description

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

See Also: SolarSystem, Barycenter, LibrationPoint, CoordinateSystem, Color

Fields

FieldDescription
3DModelFile

Allows you to load 3D models for your celestial body. Models must be in .3ds model formats.

Data Type

String

Allowed Values

. 3ds model formats only

Access

set

Default Value

empty

Units

N/A

Interfaces

GUI, script

3DModelOffsetX

This field lets you translate a celestial body in +X or -X axis of central body's coordinate system.

Data Type

Real

Allowed Values

-3.5 <= Real <= 3.5

Access

set

Default Value

0.000000

Units

N/A

Interfaces

GUI, script

3DModelOffsetY

This field lets you translate a celestial body in +Y or -Y axis of central body's coordinate system.

Data Type

Real

Allowed Values

-3.5 <= Real <= 3.5

Access

set

Default Value

0.000000

Units

N/A

Interfaces

GUI, script

3DModelOffsetZ

This field lets you translate a celestial body in +Z or -Z axis of central body's coordinate system.

Data Type

Real

Allowed Values

-3.5 <= Real <= 3.5

Access

set

Default Value

0.000000

Units

N/A

Interfaces

GUI, script

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

Real

Allowed Values

-180 <= Real <= 180

Access

set

Default Value

0.000000

Units

Deg.

Interfaces

GUI, script

3DModelRotationY

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

Real

Allowed Values

-180 <= Real <= 180

Access

set

Default Value

0.000000

Units

Deg.

Interfaces

GUI, script

3DModelRotationZ

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

Real

Allowed Values

-180 <= Real <= 180

Access

set

Default Value

0.000000

Units

Deg.

Interfaces

GUI, script

3DModelScale

Allows you to apply a scale factor to the celestial body's model size.

Data Type

Real

Allowed Values

0.001 <= Real <= 1000

Access

set

Default Value

10

Units

N/A

Interfaces

GUI, script

CentralBody

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

Data Type

String

Allowed Values

Comet, Planet, Asteroid, or Moon

Access

set

Default Value

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

Units

N/A

Interfaces

GUI, script

EquatorialRadius

The body's equatorial radius.

Data Type

Real

Allowed Values

Real > 0

Access

set

Default Value

6378.1363

Units

km

Interfaces

GUI, script

EopFileName

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

Filename

Allowed Values

Valid file name

Access

set

Default Value

''

Units

N/A

Interfaces

script

FileName

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

Data Type

String

Allowed Values

A file of the following format:

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

Access

set

Default Value

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

Units

N/A

Interfaces

GUI, script

Flattening

The body's polar flattening.

Data Type

Real

Allowed Values

Real >= 0

Access

set

Default Value

0.0033527

Units

N/A

Interfaces

GUI, script

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

String array

Allowed Values

Paths to valid SPICE FK files

Access

set

Default Value

Varies for built-in bodies. Empty for user-defined bodies.

Units

N/A

Interfaces

GUI, script

Mu

The body's gravitational parameter.

Data Type

Real

Allowed Values

Real > 0

Access

set

Default Value

398600.4415

Units

km^3/s^2

Interfaces

GUI, script

NAIFId

NAIF Integer ID for body.

Data Type

Integer

Allowed Values

Integer

Access

set

Default Value

-123456789

Units

N/A

Interfaces

GUI, script

NutationUpdateInterval

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

Data Type

Real

Allowed Values

Real >= 0

Access

set

Default Value

60

Units

sec.

Interfaces

GUI, script

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

Integer Array or String

Allowed Values

Any color available from the Orbit Color Picker in GUI. Valid predefined color name or RGB triplet value between 0 and 255.

Access

set

Default Value

Orchid for user-defined Planet, Pink for user-defined Comet, Salmon for user-defined Asteroid and Tan for user-defined Moon

Units

N/A

Interfaces

GUI, script

OrbitSpiceKernelName

List of SPK kernels. Providing emtpy brackets unloads previously loaded kernels.

Data Type

Reference array

Allowed Values

valid array of SPK kernels

Access

set

Default Value

N/A

Units

N/A

Interfaces

GUI, script

OrientationEpoch

The reference epoch for orientation data.

Data Type

String

Allowed Values

6116.0 <= Epoch <= 58127.5

Access

set

Default Value

21545.0

Units

A1 Modified Julian Epoch

Interfaces

GUI, script

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

String array

Allowed Values

Paths to valid SPICE PCK files

Access

set

Default Value

Varies for built-in bodies. Empty for user-defined bodies.

Units

N/A

Interfaces

GUI, script

PosVelSource

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

Data Type

String

Allowed Values

SPICE

Access

set

Default Value

DE405 for built-in bodies. SPICE for user-defined bodies.

Units

N/A

Interfaces

GUI, script

RotationConstant

The body's spin angle at the orientation epoch.

Data Type

Real

Allowed Values

Real

Access

set

Default Value

190.147

Units

deg

Interfaces

GUI, script

RotationDataSource

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

Data Type

String

Allowed Values

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

Access

set

Default Value

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

Units

N/A

Interfaces

GUI, script

RotationRate

The body's spin rate.

Data Type

Real

Allowed Values

Real

Access

set

Default Value

360.9856235

Units

deg/day

Interfaces

GUI, script

SpiceFrameId

SPICE ID of body-fixed frame. Used to define celestial body properties for use with ContactLocator and EclipseLocator. See Remarks.

Data Type

String

Allowed Values

Valid SPICE frame ID (text or numeric)

Access

set

Default Value

Varies for built-in bodies. Empty for user-defined bodies.

Units

N/A

Interfaces

GUI, script

SpinAxisDECConstant

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

Data Type

Real

Allowed Values

Real

Access

set

Default Value

90

Units

deg

Interfaces

GUI, script

SpinAxisDECRate

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

Data Type

Real

Allowed Values

Real

Access

set

Default Value

-0.5570

Units

deg/century

Interfaces

GUI, script

SpinAxisRAConstant

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

Data Type

Real

Allowed Values

Real

Access

set

Default Value

-0.641

Units

deg

Interfaces

GUI, script

SpinAxisRARate

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

Data Type

Real

Allowed Values

Real

Access

set

Default Value

-0.641

Units

deg/century

Interfaces

GUI, script

TargetColor

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

Integer Array or String

Allowed Values

Any color available from the Orbit Color Picker in GUI. Valid predefined color name or RGB triplet value between 0 and 255.

Access

set

Default Value

Dark Gray for built-in or user-defined Planet, Comet, Asteroid and Moon

Units

N/A

Interfaces

GUI, script

TextureMapFileName

Allows you to load a texture map file for your celestial body.

Data Type

String

Allowed Values

texture map files in jpeg format

Access

set

Default Value

'GenericCelestialBody.jpg'

Units

N/A

Interfaces

GUI, script

GUI

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

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

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

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

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

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

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

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

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.

Remarks

Celestial body orientation model

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

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

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

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

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

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

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

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

CoordinateSystem

CoordinateSystem — An axis and origin pair

Description

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

See Also: Spacecraft, Calculation Parameters, OrbitView

Fields

FieldDescription
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

Real

Allowed Values

-∞ < Real < ∞ (norm of AlignmentVector >= 1e-9)

Access

set

Default Value

1

Units

N/A

Interfaces

gui,script

AlignmentVectorY

The y 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

Real

Allowed Values

-∞ < Real < ∞ (norm of AlignmentVector>= 1e-9)

Access

set

Default Value

0

Units

N/A

Interfaces

gui, script

AlignmentVectorZ

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

Real

Allowed Values

-∞ < Real < ∞ (norm of AlignmentVector>= 1e-9)

Access

set

Default Value

0

Units

N/A

Interfaces

gui,script

Axes

The axes of the CoordinateSystem.

Data Type

String

Allowed Values

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

Access

set

Default Value

MJ2000Eq

Units

N/A

Interfaces

GUI, script

ConstraintVectorX

The x component of the ConstraintVector expressed in the local frame (for example, expressed in the LocalAlignedConstrained frame). Used for the following axis systems: LocalAlignedConstrained.

Data Type

Real

Allowed Values

-∞ < Real < ∞ (norm of ConstraintVector>= 1e-9)

Access

set

Default Value

0

Units

N/A

Interfaces

gui,script

ConstraintVectorY

The y component of the ConstraintVector expressed in the local frame (for example, expressed in the LocalAlignedConstrained frame). Used for the following axis systems: LocalAlignedConstrained.

Data Type

Real

Allowed Values

-∞ < Real < ∞ (norm of ConstraintVector>= 1e-9)

Access

set

Default Value

0

Units

N/A

Interfaces

gui,script

ConstraintVectorZ

The z component of the ConstraintVector expressed in the local frame (for example, expressed in the LocalAlignedConstrained frame). Used for the following axis systems: LocalAlignedConstrained.

Data Type

Real

Allowed Values

-∞ < Real < ∞ (norm of ConstraintVector>= 1e-9)

Access

set

Default Value

1

Units

N/A

Interfaces

gui,script

ConstraintReferenceVectorX

The x component of the ConstraintReferenceVector expressed in the ConstraintCoordinateSystem. Used for the following axis systems: LocalAlignedConstrained.

Data Type

Real

Allowed Values

-∞ < Real < ∞ (norm of ConstraintReferenceVector>= 1e-9)

Access

set

Default Value

0

Units

N/A

Interfaces

gui,script

ConstraintReferenceVectorY

The y component of the ConstraintReferenceVector expressed in the ConstraintCoordinateSystem. Used for the following axis systems: LocalAlignedConstrained.

Data Type

Real

Allowed Values

-∞ < Real < ∞ (norm of ConstraintReferenceVector>= 1e-9)

Access

set

Default Value

0

Units

N/A

Interfaces

gui,script

ConstraintReferenceVectorZ

The z component of the ConstraintReferenceVector expressed in the ConstraintCoordinateSystem. Used for the following axis systems: LocalAlignedConstrained.

Data Type

Real

Allowed Values

-∞ < Real < ∞ (norm of ConstraintReferenceVector>= 1e-9)

Access

set

Default Value

1

Units

N/A

Interfaces

gui,script

Constraint Coordinate System

The coordinate system for the ConstraintReferenceVector. Used for the following axis sytems: LocalAlignedConstrained.

Data Type

Resource

Allowed Values

CoordinateSystem

Access

set

Default Value

EarthMJ2000Eq

Units

N/A

Interfaces

gui,script

Epoch

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

Data Type

String

Allowed Values

A1 Modified Julian epoch.

Access

set

Default Value

21545

Units

Modified Julian Date

Interfaces

GUI, script

Origin

The origin of the CoordinateSystem.

Data Type

String

Allowed Values

CelestialBody, Spacecraft, LibrationPoint, Barycenter, SolarSystemBarycenter, GroundStation

Access

set

Default Value

Earth

Units

N/A

Interfaces

GUI, script

Primary

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

Data Type

String

Allowed Values

CelestialBody, Spacecraft, LibrationPoint, Barycenter, SolarSystemBarycenter, GroundStation

Access

set

Default Value

Earth

Units

N/A

Interfaces

GUI, script

ReferenceObject

The reference object for a LocalAlignedConstrained axis system. The axes are computed such that the AlignmentVector in the body frame is aligned with the vector pointing from the Origin to the ReferenceObject.

Data Type

Resource

Allowed Values

A Resource that has coordinates. For example: CelestialBody, Spacecraft, LibrationPoint, Barycenter, SolarSystemBarycenter, GroundStation.

Access

set

Default Value

Luna

Units

N/A

Interfaces

gui,script

Secondary

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

Data Type

String

Allowed Values

CelestialBody, Spacecraft, LibrationPoint, Barycenter, SolarSystemBarycenter, GroundStation

Access

set

Default Value

Luna

Units

N/A

Interfaces

GUI, script

XAxis

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

Data Type

String

Allowed Values

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

Access

set

Default Value

R

Units

N/A

Interfaces

GUI, script

YAxis

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

Data Type

String

Allowed Values

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

Access

set

Default Value

No Default

Units

N/A

Interfaces

GUI, script

Zaxis

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

Data Type

String

Allowed Values

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

Access

set

Default Value

N

Units

N/A

Interfaces

GUI, script

GUI

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

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

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

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

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.

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

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

Computation of ICRF and ITRF Axes using IAU2000 Conventions

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

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

Computation of ObjectReference Axis System

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

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

Warning

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

Overview of Built-in Coordinate Systems

NameOriginAxesDescription
EarthMJ2000EqEarthMJ2000Eq

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

EarthMJ2000EcEarthMJ2000Ec

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

EarthFixedEarthBodyFixed

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

EarthICRFEarthICRF

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

Description of Axes Types

Axes NameOrigin LimitationsBase TypeDescription
MJ2000EqNoneIAU-1976 FK5

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

MJ2000EcNoneIAU-1976 FK5

An inertial coordinate system. The x-axis points along the line formed by the intersection of the Earth’s mean equator and the mean ecliptic plane at the J2000 epoch. The z-axis is normal to the mean 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.

ICRFNoneIAU-2000

An inertial coordinate system. The axes are close to the mean Earth equator and pole at the J2000 epoch, and at the Earth’s surface, the RSS difference between vectors expressed in MJ2000Eq and ICRF is less than 1 m. Note that since MJ2000Eq and ICRF are imperfect realizations of inertial systems, the transformation between them is time varying. This axis system is computed using IAU-2000A theory with 2006 update for precession.

LocalAlignedConstrainedNoneIAU-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.

MODEqNoneIAU-1976 FK5

A quasi-inertial coordinate system referenced to Earth’s mean equator at the current epoch. The current epoch is defined by the context of use and usually comes from the spacecraft or graphics epoch. This system is computed using IAU-1976/FK5 theory with 1980 update for nutation.

MODEcNoneIAU-1976 FK5

A quasi-inertial coordinate system referenced to the mean ecliptic at the current epoch. The current epoch is defined by the context of use and usually comes from the spacecraft or graphics epoch. This system is computed using IAU-1976/FK5 theory with 1980 update for nutation.

TODEqNoneIAU-1976 FK5

A quasi-inertial coordinate system referenced to Earth’s true equator at the current epoch. The current epoch is defined by the context of use and usually comes from the spacecraft or graphics epoch. This system is computed using IAU-1976/FK5 theory with 1980 update for nutation.

TODEcNoneIAU-1976 FK5

A quasi-inertial coordinate system referenced to Earth’s true ecliptic at the current epoch. The current epoch is defined by the context of use and usually comes from the spacecraft or graphics epoch. This system is computed using IAU-1976/FK5 theory with 1980 update for nutation.

MOEEqNoneIAU-1976 FK5

A quasi-inertial coordinate system referenced to Earth’s mean equator at the reference epoch. The reference epoch is defined on the CoordinateSystem object. This system is computed using IAU-1976/FK5 theory with 1980 update for nutation.

MOEEcNoneIAU-1976 FK5

A quasi-inertial coordinate system referenced to the mean ecliptic at the reference epoch. The reference epoch is defined on the CoordinateSystem object. This system is computed using IAU-1976/FK5 theory with 1980 update for nutation.

TOEEqNoneIAU-1976 FK5

A quasi-inertial coordinate system referenced to Earth’s true equator at the reference epoch. The reference epoch is defined on the CoordinateSystem object. This system is computed using IAU-1976/FK5 theory with 1980 update for nutation.

TOEEcNoneIAU-1976 FK5

A quasi-inertial coordinate system referenced to the true ecliptic at the reference epoch. The reference epoch is defined on the CoordinateSystem object. This system is computed using IAU-1976/FK5 theory with 1980 update for nutation.

ObjectReferencedNoneIAU-1976 FK5

An ObjectReferenced system is a CoordinateSystem whose axes are defined by the motion of one object with respect to another object. See the discussion above for a detailed description of the ObjectReferenced axis system.

EquatorCelestial BodyIAU-1976 FK5

A true of date equator axis system for the celestial body selected as the origin. The Equator system is defined by the body’s equatorial plane and its intersection with the ecliptic plane, at the current epoch. The current epoch is defined by the context of use and usually comes from the spacecraft or graphics epoch. The Equator system for Earth is computed using IAU-1976/FK5 theory. For the Moon, the Equator system is computed using the theory selected in the field Luna.RotationDataSource. For other built-in celestial bodies, the body fixed axes are computed using models provided by the IAU in “Report of the IAU/IAG Working Group on Cartographic Coordinates and Rotational Elements of the Planets and Satellites: 2000”.

BodyFixedCelestial Body or SpacecraftIAU-1976 FK5

The BodyFixed axis system is referenced to the body equator and the prime meridian of the body. The BodyFixed system for Earth is computed using IAU-1976/FK5 theory. For the Moon, the BodyFixed system is computed using the theory selected in the field Luna.RotationDataSource. For other built-in celestial bodies, the body fixed axes are computed using models provided by the IAU in “Report of the IAU/IAG Working Group on Cartographic Coordinates and Rotational Elements of the Planets and Satellites: 2000”.

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.

BodyInertialCelestial BodyIAU-1976 FK5

An inertial system referenced to the equator ( at the J2000 epoch ) of the celestial body selected as the origin of the CoordinateSystem. Because the BodyInertial axis system uses different theories for different bodies, the following definitions describe only the nominal axis configurations. The x-axis points along the line formed by the intersection of the bodies equator and earth’s mean equator at J2000. The z-axis points along the body's spin axis direction at the J2000 epoch. The y-axis completes the right-handed set. For Earth, the BodyInertial axis system is identical to the MJ2000Eq system. For the Moon, the orientation at the J2000 epoch is computed using the theory selected in the field Luna.RotationDataSource. For all other built-in celestial bodies, the BodyInertial axis system is based upon the IAU report entitled “Report of the IAU/IAG Working Group on Cartographic Coordinates and Rotational Elements of the Planets and Satellites: 2000”

GSENoneIAU-1976 FK5

The Geocentric Solar Ecliptic system. The x-axis points from Earth to the Sun. The z-axis is defined as the cross product RxV where R and V are earth’s position and velocity with respect to the sun respectively. The y-axis completes the right-handed set. The GSE axes are computed using the relative motion of the Earth and Sun even if the origin is not Earth.

GSMNoneIAU-1976 FK5

The Geocentric Solar Magnetic system. The x-axis points from Earth to the Sun. The z-axis is defined to be orthogonal to the x-axis and lies in the plane of the x-axis and Earth’s magnetic dipole vector. The y-axis completes the right-handed set. The GSM axes are computed using the relative motion of the Earth and Sun even if the origin is not Earth.

TopocentricEarthIAU-1976 FK5

A GroundStation-based coordinate system. The y-axis points due East and the z-axis is normal to the local horizon. The x-axis completes the right handed set.

BodySpinSunCelestial BodyIAU-1976 FK5

A celestial body spin-axis-referenced system. The x-axis points from the celestial body to the Sun. The y-axis is computed as the cross product of the x-axis and the body's spin axis. The z-axis completes the right-handed set.

Examples

Define a Spacecraft’s state in EarthFixed coordinates.

Create Spacecraft aSpacecraft
aSpacecraft.CoordinateSystem = EarthFixed
aSpacecraft.X = 7100
aSpacecraft.Y = 0
aSpacecraft.Z = 1300
aSpacecraft.VX = 0
aSpacecraft.VY = 7.35
aSpacecraft.VZ = 1

Report a Spacecraft’s state in GroundStation Topocentric coordinates.

Create Spacecraft aSat
Create Propagator aProp
Create GroundStation aStation

Create CoordinateSystem stationTopo
stationTopo.Origin = aStation
stationTopo.Axes   = Topocentric

Create ReportFile aReport
aReport.Filename = 'ReportFile1.txt'
aReport.Add = {aSat.stationTopo.X aSat.stationTopo.Y aSat.stationTopo.Z ... 
               aSat.stationTopo.VX aSat.stationTopo.VY aSat.stationTopo.VZ}

BeginMissionSequence

Propagate aProp(aSat) {aSat.ElapsedSecs = 8640.0}

View a trajectory in an ObjectReferenced, rotating-LibrationPoint system.

%  Create the Earth-Moon Barycenter and Libration Point
Create Barycenter EarthMoonBary
EarthMoonBary.BodyNames = {Earth,Luna};

Create LibrationPoint SunEarthMoonL1
SunEarthMoonL1.Primary   = Sun;
SunEarthMoonL1.Secondary = EarthMoonBary
SunEarthMoonL1.Point     = L1;

%  Create the coordinate system
Create CoordinateSystem RotatingSEML1Coord
RotatingSEML1Coord.Origin    = SunEarthMoonL1
RotatingSEML1Coord.Axes      = ObjectReferenced
RotatingSEML1Coord.XAxis     = R
RotatingSEML1Coord.ZAxis     = N
RotatingSEML1Coord.Primary   = Sun
RotatingSEML1Coord.Secondary = EarthMoonBary

%  Create the spacecraft and propagator
Create Spacecraft aSpacecraft
aSpacecraft.DateFormat       = UTCGregorian
aSpacecraft.Epoch            = '09 Dec 2005 13:00:00.000'
aSpacecraft.CoordinateSystem = RotatingSEML1Coord
aSpacecraft.X  = -32197.88223741966
aSpacecraft.Y  = 211529.1500044117
aSpacecraft.Z  = 44708.57017366499
aSpacecraft.VX = 0.03209516489451751
aSpacecraft.VY = 0.06100386504053736
aSpacecraft.VZ = 0.0550442738917212

Create Propagator aPropagator
aPropagator.FM           = aForceModel
aPropagator.MaxStep = 86400
Create ForceModel aForceModel
aForceModel.PointMasses = {Earth,Sun,Luna}

% Create a 3-D graphic
Create OrbitView anOrbitView
anOrbitView.Add                  = {aSpacecraft,  Earth, Sun, Luna}
anOrbitView.CoordinateSystem     = RotatingSEML1Coord
anOrbitView.ViewPointReference   = SunEarthMoonL1
anOrbitView.ViewPointVector      = [-1500000 0 0 ]
anOrbitView.ViewDirection        = SunEarthMoonL1
anOrbitView.ViewUpCoordinateSystem = RotatingSEML1Coord
anOrbitView.Axes                 = Off
anOrbitView.XYPlane              = Off

BeginMissionSequence

Propagate aPropagator(aSpacecraft, {aSpacecraft.ElapsedDays = 180})

ContactLocator

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 (ObserverTarget) or receive sense (ObserverTarget) 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 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

FieldDescription
Filename

Name and path of the contact report file. This field can be set in the mission sequence.

Data Type

String

Allowed Values

Valid file path

Access

set

Default Value

'ContactLocator.txt'

Units

N/A

Interfaces

GUI, script

FinalEpoch

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

String

Allowed Values

Valid epoch in available spacecraft ephemeris

Access

set

Default Value

'21545.138'

Units

ModifiedJulian epoch formats: days

Gregorian epoch formats: N/A

Interfaces

GUI, script

InitialEpoch

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

String

Allowed Values

Valid epoch in available spacecraft ephemeris

Access

set

Default Value

'21545'

Units

ModifiedJulian epoch formats: days

Gregorian epoch formats: N/A

Interfaces

GUI, script

LightTimeDirection

Sense of light-time calculation: transmit from observer or receive at observer. The clock is always hosted on the Target.

Data Type

Enumeration

Allowed Values

Transmit, Receive

Access

set

Default Value

Transmit

Units

N/A

Interfaces

GUI, script

Observers

List of the contact observer objects. Can be any number of GMAT GroundStation resources.

Data Type

List of GroundStation resources

Allowed Values

Any existing GroundStation resources

Access

set

Default Value

Empty list

Units

N/A

Interfaces

GUI, script

OccultingBodies

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

List of CelestialBody resources (e.g. Planet, Asteroid, Moon, etc.)

Allowed Values

Any existing CelestialBody-class resources

Access

set

Default Value

Empty list

Units

N/A

Interfaces

GUI, script

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

Enumeration

Allowed Values

Automatic, Manual, Disabled

Access

set

Default Value

'Automatic'

Units

N/A

Interfaces

GUI, script

StepSize

Step size of event locator. See Remarks for discussion of appropriate values.

Data Type

Real

Allowed Values

StepSize > 0

Access

set

Default Value

10

Units

s

Interfaces

GUI, script

Target

The target Spacecraft resource to search for contacts.

Data Type

Spacecraft resource

Allowed Values

Any existing Spacecraft resource

Access

set

Default Value

First configured Spacecraft resource

Units

N/A

Interfaces

GUI, script

UseEntireInterval

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

Boolean

Allowed Values

true, false

Access

set

Default Value

true

Units

N/A

Interfaces

GUI, script

UseLightTimeDelay

Use light-time delay in the event-finding algorithm. The clock is always hosted on the Observer.

Data Type

Boolean

Allowed Values

true, false

Access

set

Default Value

true

Units

N/A

Interfaces

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

Boolean

Allowed Values

true, false

Access

set

Default Value

true

Units

N/A

Interfaces

GUI, script

WriteReport

Write an event report when event location is executed. This field can be set in the mission sequence.

Data Type

Boolean

Allowed Values

true, false

Access

set

Default Value

true

Units

N/A

Interfaces

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.

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.

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 light-time 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.

 UseEntireInterval trueUseEntireInterval false
UseLightTimeDelay true
Effective interval

LightTimeDirection = 'Transmit': [t0+lt, tf]

LightTimeDirection = 'Receive': [t0, tf-lt]

Discontinuous intervals

Unsupported. Behavior is undefined.

Effective interval

[InitialEpoch, FinalEpoch]

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.

  • 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 root-location 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)            Stop Time (UTC)               Duration (s)         
01 Jan 2000 13:18:45.268    01 Jan 2000 13:29:54.824      669.55576907    
01 Jan 2000 15:06:44.752    01 Jan 2000 15:18:22.762      698.01023654    


Number of events : 2


Observer: GroundStation2
Start Time (UTC)            Stop Time (UTC)               Duration (s)         
01 Jan 2000 13:36:13.792    01 Jan 2000 13:47:51.717      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

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}
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'
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

DifferentialCorrector

DifferentialCorrector — A numerical solver

Description

A DifferentialCorrector (DC) is a numerical solver for solving boundary value problems. It is used to refine a set of variable parameters in order to meet a set of goals defined for the modeled mission. The DC in GMAT 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

FieldDescription
Algorithm

The numerical method used to solve the boundary value problem.

Data Type

String

Allowed Values

NewtonRaphson, Broyden, ModifiedBroyden

Access

set

Default Value

NewtonRaphson

Units

N/A

Interfaces

GUI, script

DerivativeMethod

Chooses between one-sided and central differencing for numerically determining the derivative. Only used when Algorithm is set to NewtonRaphson.