How to Add an Orbit State Type

Owned by Wendy C. Shoan
Last updated: May 22, 2013Version comment
4 min read


How to Add an Orbit State Type to GMAT

Wendy C. Shoan
Goddard Space Flight Center

Introduction

GMAT provides the capability to model spacecraft orbits.  As of R2013a, there are six orbit state representations allowed in GMAT: Cartesian, Keplerian, Modified Keplerian, SphericalAZFPA, SphericalRADEC, and Equinoctial.  

This document will first give a brief overview of how GMAT handles these state types.  Then it will explain how to add a new orbit state type to GMAT.  Due to current design, new state types cannot be added by plugins and so GMAT base code must be modified.  The implementation of a new orbit state type will involve, at a high level:

  • Modifying the Spacecraft class to handle the new type
  • Adding conversions methods in StateConversionUtil
  • Adding new parameters to GMAT for the fields associated with your new state type
  • Modifying the Orbit tab of the Spacecraft panel 

State Type Overview

The user can set a spacecraft's orbital state in any of the above-mentioned representations via the script or the Orbit tab of the Spacecraft panel.  Internal computations are done in Cartesian.  The StateConversionUtil static class provides conversion methods between the available representations, usually going through the Cartesian state.  Uses can plot or report state data in any of the allowed representations.

Adding a State Type 

Step 1: Modify Spacecraft.hpp

There are minimal changes needed for the header file when adding a new state type.  The new elements must be added to the end of the MultipleReps enum, and the state type must be added to the end of the STATE_REPS enum.  For example, if we were adding the Delaunay type:

and

Step 2: Modify Spacecraft.cpp

You will need to add your new elements to the MULT_REP_STRINGS array to match the data you added to the header, e.g. 

You will need to modify other Spacecraft methods as follows:

  • in the constructor, you will need to add your new type to the representations vector
  • in GetParameterID, you will need to add your new elements
  • in SetStringParameter, in the code for DISPLAY_STATE_TYPE_ID, you will need to add your new state type in the check for valid input type
  • in UpdateElementLabels, set the labels for your elements
  • in SetElement, add checks for elements that could be part of other representations (e.g. AOP, RAAN, or MA for Delaunay)
  • in LookUpLabel, add your element labels
  • in BuildElementLabelMap, add your element labels
  • in SetPossibleInputTypes, you will need to make sure your new type is included or removed where applicable
  • in ValidateOrbitStateValue, add validation where necessary

Step 3: Modify StateConversionUtil

  • add your new type to the StateType enum
  • add your new type to the STATE_TYPE_TEXT string array
  • add your bool value to the REQUIRES_CB_ORIGIN array - set it to true if your new state type requires that the origin be a CelestialBody; false otherwise
  • you may need to add a constant (e.g. a tolerance value) as well
  • provide conversion methods to/from your new type and Cartesian, e.g. CartesianToDelaunay and DelaunayToCartesian.  See example below - you may need more arguments for your conversions, or you may need a larger Rvector for your state type.  These methods should also include all validation necessary - checking for singularities, disallowed orbits, etc.  You will need to modify ValidateValue to check for range of data, values of coupled data, etc.  For example:
  • you will then need to modify the main Convert methods to call your new methods, as needed

Step 4: Add the new parameters

You will need to add classes and modify others to add parameters for your new state type elements.

  • add a header and source file for your new parameters. e.g DelaunayParameters.  There will actually be several classes defined in this file, one for each of your new elements.  Each class must derive from the appropriate parameter class.  For example, a single real parameter would derive from OrbitReal (see EquinoctialParameters for an example)
  • you will need to modify OrbitData.hpp to add an enumerated type for your sate type, add a method to return the state in your new type, e.g. GetDelaunayState(), add two other methods to return a real value with either an integer id or a string label as input, e.g. 
  • modify OrbitData.cpp to add your elements to SetReal, and implement your Get<state-type>State and Get<state-type>Real methods
  • modify ParameterFactor.cpp to add your elements to CreateParameter and the creatables list
  • if you wish to add default parameters, add your new ones to Moderator::CreateDefaultParameters

Step 5: Update the Orbit Panel

Code mods will be needed to OrbitPanel.  You will need to add/modify at least the following:

  • add a Check<state-type> method to validate user input values for your elements, as necessary
  • modify CheckState to call your new method when the user has entered elements in your new state
  • add/modify widgets as needed