Feature Spec and Test Procedures

 

 

Spec User’s Guide

Explore

Known Bugs

Failing Tests

Other Findings

Requirements

Interface/Functional Spec

Overview

Fields

GUI

Remarks

Examples

Warnings/Errors

Test Considerations/Comments

Test Procedures

Assumptions

Existing Tests

Recommended Additional Tests

 

Spec User’s Guide

Explore

This section is to document an initial list all known issues with this feature. Put findings here during feature exploration.  This is a temporary holding place, and all of these items MUST be moved to JIRA early in the feature finalization or they will not be tracked or scheduled to be fixed!

Bugs and Findings

Issue 1: Done STM partials are not implemented for all forces

Recommendation: Throw a warning if STM is requested for forces that don't have partials implemented, add to user docs.

 

 

Issue 2:Done  MarsGRAMM not implemented in GUI or tested.

Recommendation: Don't include in production release, include as plugin. (Priority: P3, FixBy: Someday)

 

Issue 3: Done MSISE00 and MSISE86 are not avialable in GUI.

Recommendation: Add them to the list of Earth models, this is trivial (Priority: P1, FixBy: 2012a)

 

Issue 4: Committed: Tide model tests are meter level different from STK truth

Recommendation: Submit a minor bugand change tolerance in tc files. We don't even know if our models are the same and

the differences are very small. (Priority: P3, FixBy: Someday)

 

Issue 5: Tracking as separate feature. SPK propagator has many bugs.

Recommendation: Move to a plugin. If we have time, we can do V&V after all P1 features are ready. If not, we'll turn it off and call it a beta. I think we should put this early in the schedule because we need to know if pulling into a plugin is going to cause problems in base and GUI code.(Priority: P1, FixBy: 2012a)

 

Issue 6: Done. STM tests don't meet tolerance.

Recommendation: Get FreeFlyer files and rerun with more accurate integration tolerances. I believe the truth data

was not generated with tight integration tolerances. (Priority: P2, FixBy: Production)

 

Issue 7: Done: Disallowed.Setting ForceModel fields in Command mode does not work.

Recommendation: Look at the design and see why this is occurring. I can execute a complex force model test in a GMAT function, which is all executed in command mode, and the answers are correct. So I don't see why the behavior is wrong in when using a script. I hope we can fix this with some design and refactoring. As a last resort, if there is too much work, then we can throw an exception if setting fields in command mode. (Priority: P1, FixBy: 2012a)

 

Issue 8: Done. Many dynamics model tests are failing because there are different number of rows in the truth files. This is most likely due to a

bug in STK that causes it to output too many rows in a report.

Recommendation: We should talk to STK rep to see when this bug was fixed and try rerunning the truth scenarios in that version. (Priority: P1, FixBy: 2012a)

 

Issue 9: Done. Tide model tests are failing. They used to pass.

Recommendation: JIRA bug is checked in. Fix them. (Priority: P1, FixBy: 2012a)

 

Issue 10: Done. Relativistic correction not available in GUI.

Recommendation: Add a check box for it. (Priority: P1, FixBy: 2012a)

 

Issue 11: Done: Documented. Tide model not available in GUI.

Recommendation: Not sure, one possiblity is to only support via script. However, if command mode settings for propagator don't

support this (see issue above) then GUI user's won't be able to use this model. In that case, we should add to the GUI. (Priority: P2, FixBy: Production)

 

Issue 12: Done. Drag Model Setup panel says "File Input: to be implemented"

Recommendation: Remove the text and uneditable widgets. (Priority: P1, FixBy: 2012a)

 

Issue 13:  Ignoring. Propagator dialog box code is a mess and needs to be either refactored or thrown out and start from scratch.

Recommendation: Sigh. Wait on this and get what we have working. (Priority: P3, FixBy: Someday)

 

Issue 14: Done. We currently only allow one Primary Body and it must be the same as the central body. However, the GUI let's you set them differently and then throws and a run-time exception.

Recommendation: Make one of the fields read only and dependent upon the other. Work closely with Bez because this change will break many regression tests. My suggestion is to make central body dependent upon Primary body because there is a lot of complexity with changing central body and interactions with other fields in the GUI. (Priority: P1, FixBy: 2012a)

 

Issue 15: Done: Documented. SRP fields SRP.Flux, SRP.Nominal_Sun, and SRP.Flux_Pressure are not settable from the GUI. These two settings are currently missing from the spec as well. If my understanding is correct, SRP.Flux_Pressure is an obsolete parameter that is dependent upon SRP.Flux and SRP.NominalSun. We need to clarify what the SRP.Flux_Pressure is for and if it is obsolete then we should deprecate it.

Recommendation: Document the fields and show script examples. I'm torn over the GUI, given the command mode issue above, and the fact that every user of GMAT will use a propagator, I think we should consider putting in a setup panel for this. I suggest triaging as (Priority: P2, FixBy: Production)

 

Issue 16: Committed. Many error and warning messages are crytpic and not end-user oriented.

Recommendation: Time box this issue, organize output from all validation tests, and SPH and DJC spend a few days fixing the most cryptic error messages. (Priority: P3, FixBy: Someday)

 

Issue 17: SRP variational terms partially complete: the partial derivative when the spacecraft is in partial shadow is not included.

Recommendation: Document then change status to (Priority: P3, FixBy: Someday)

 

Issue 18: Done: Documented. Some script fields are "turned off" when other script "flags" are switched causing you to comment out chunks of script to get a buildable script. For example if you are using MSISE90 drag and have flux fields set up, if you change Drag to None, the script won't build unless you comment out the flux fields.

Recommandation: Determine if there is a design reason for doing this and if it the behavior can be changed so that the fields are settable even when drag is None. If this is more than a few hours work, check in as (Priority: P3, FixBy: Someday).

Recommendation:

 

      Drag setup options are not displayed in the GUI.

      Adding mulitple forces of the same forces to a force model causes invalid superposition.

Questions

1         Can the Model field be used from the script.  Need to ask WCS how this works if it is supported?

2         Spec lists RelativisticCorrection and SRP as an Enumeration type.  Is that correct?

3         Can’t finish spec until user defined is spec’d.

4         Need to write new range tests for new range requirements on many ForceModel fields

Requirements

 

 

FRR-13.1.0

The system shall support the following dynamics models:

FRR-13.1.1.0

1)      Non-spherical central body

FRR-13.1.1.1

                                                               i.      Default Body

FRR-13.1.1.2

                                                             ii.      User-defined body

FRR-13.1.2.0

2)      Drag with the following density models

FRR-13.1.2.1.0

                                                               i.      Jacchia-Roberts

FRR-13.1.2.1.1

1.                 Constant solar

FRR-13.1.2.1.2

2.                 Average flux

FRR-13.1.2.1.3

2.                 Geomagnetic index

FRR-13.1.2.2.0

                                                             ii.      MSISE-90

FRR-13.1.2.2.1

1.                 Constant solar

FRR-13.1.2.2.2

2.                 Average flux

FRR-13.1.2.2.3

2.                 Geomagnetic index

FRR-13.1.2.4.0

                                                           iv.      MSISE-86

FRR-13.1.2.4.1

1.                 Constant solar

FRR-13.1.2.4.2

2.                 Average flux

FRR-13.1.2.4.3

2.                 Geomagnetic index

DEFERRED

                                                           v.      Mars-GRAMM

DEFERRED

1.                 Density Models

DEFERRED

i.                 Low

DEFERRED

ii.                 Mean

DEFERRED

iii.                 High

DEFERRED

2.     Mars-GRAM input file

FRR-13.1.2.6.0

                                       vi.               NRLMISISE-00

FRR-13.1.2.6.1

1.                 Constant solar

FRR-13.1.2.6.2

2.                 Average flux

FRR-13.1.2.6.3

2.                 Geomagnetic index

FRR-13.1.3.0

3)      Drag with the following spacecraft models:

FRR-13.1.3.1

                                                               i.      Canon ball model

FRR-13.1.4.0

4)      Solar Radiation Pressure:

FRR-13.1.4.1

                                                               i.      Canon ball model

FRR-13.1.5.0

5)      Point mass perturbations:

FRR-13.1.5.1

                                                               i.      8 major planets

FRR-13.1.5.2

                                                             ii.      Pluto

FRR-13.1.5.3

iii. User defined celestial body as defined in FRR-16

FRR-13.1.6.0

6)      Solid Earth Tides

FRR-13.1.6.1

                                          i.     Solid and Pole Tides

FRR-13.1.7

7)      Relativistic Correction

FRR-13.2.0

The system shall optionally propagate the following quantities:

FRR-13.2.1

1)      Orbit Cartesian state

FRR-13.2.2

2)      Orbit state transition matrix

FRR-13.3

The system shall propagate the equations of motion with respect to the Earth’s mean equator axes at the J2000 epoch as defined by the FK5 reduction.

FRR-13.4

The system shall propagate the equations of motion with respect to any celestial body defined in FRR-16.

 

Interface/Functional Spec

Overview

 

A ForceModel is a model of the environmental forces and dynamics that affect the motion of a spacecraft.  GMAT supports numerous force models such as point mass and spherical harmonic gravity models, atmospheric drag, solar radiation pressure, tide models and relativistic corrections.  A ForceModel is configured and attached to the Propagator object (see the Propagator object for differences between script and GUI configuration when configuring a Propagator). The Propagator, along with the Propagate command, uses a Force model to numerically solve the orbital equations of motion (forwards or backwards in time) using the forces configured in the ForceModel object, and may include thrust terms in the case of powered flight. See the Remarks and Examples below for detailed information on how to configure force models for your application. 

 

See Also:  Propagator, Propagate command, BeginFiniteBurn command

 

Fields

See the User Interface Spec spreadsheet for reference information for fields.

 

Open Issue: For WCS and TGG. The GUI currently allows you to set the Central body to be a different body than the Primary body. An exception is then thrown at execution.  This is not ideal behavior.  Should we link these two fields and make only one editable?  This would cause problems for Bez’s GUI system tests.  If so, should we make this a P1 must do or P2 hope to do?

 

 

 

GUI

For Developers: 

 

Nominal GUI States/Behavior:

 

The following controls are always active, always visible, and do not have states dependent upon other fields.  (See FieldSpec for range information):  

      Error Control

      Use Solar Radiaton Pressure

      SolarRadiationPressure Setup (not for R2013a)

      Relativistic Correction (not yet implemented, may be in R2012a but not sure)

 

The following controls have trivial dependencies:

      A body cannot appear simultaneously in the PrimaryBody and PointMass fields. 

      The PrimaryBody and Central Body must be the same (this will change in the future, see open issue below)

 

The following controls have complex dependencies:

      When the PrimaryBody field is set to None: all fields in the PrimaryBody group box are inactive EXCEPT the PrimaryBody combo box in the upper left hand corner of the PrimaryBody group.

      When Model is set to None: Degree, Order, PotentialFile, and Folder fields are inactive.

      When Model is set to Other, or a model defined in the startup file (see Configuring Gravitational Models section for details), the Degree, Order, PotentialFile and Folder fields are active.

      When PrimaryBody is not Earth, the Drag and DragSetup fields are inactive. When PrimaryBody is Earth, the Drag and Drag Setup fields are active.

      When the Drag Model is None, Drag Setup is inactive.

 

Transition Behavior:

      When the user changes the PrimaryBody field to a new body, Model changes to None, Potential file field is made empty, Degree and Order are set to 4.   (Future Change: I’d like to change in future versions that degree and order become zero)

      When the user changes Model from Other or a defined model to None:  Degree and Order, PotentialFile are made inactive but retain the current data. 

      When the user changes Model from one defined model to another, the only change that occurs is that the PotentialFile field displays the new model file.

 

Random Notes:

 

GMAT currently requires that the primary body is either the same as the

CentralBody or set to None. If you change you set the CentralBody

in the GUI, GMAT changes the primary body to None and you can then select between None and the CentralBody

 

We currently perform some of the validation of the Degree and Order fields at run time because it requires reading a file potentially (pun intended) provided by the user.  At run time, the file is read and the max degree and order on the file is determined.  We then validate that the required values specified by the Degree and Order fields are indeed on the file.

 

Only files with extension .cof and .grv should be selectable from the “Choose a File” dialog that opens when you click the Folder icon next to the degree and order fields.

 

If Model is selected as Other, the user must enter a file in the PotentialFile field.  If the Propagator dialog box is closed and the Potential File is empty, the following error should be thrown and the panel should not close:  “Please select a gravity file”

 

If you select a defined model type such as JGM2 from the Model pull down (assuming Earth is the Primary Body) , then you can click the Folder icon and select a file of type .grv and .cof,  GMAT should read the header text in the file and determines the model type.  If the type is a known type like JGM3, GMAT should change the Model field to JGM3. If the header has no type or is an unknown type, then GMAT should change the Model drop down to Other.

 

Note: When you delete a propagator via the GUI, it’s ForceModel is not deleted.  This is because the ForceModel may be used by other Propagators .

 

 

Remarks

 

Overview of Primary Body/Central Body and Field Interactions

 

In GMAT, a Primary body is a celestial body that is modelled with a complex force model which may include a spherical harmonic gravity model, tides, or drag.   A body cannot appear in both the PrimaryBody and PointMasses fields.    GMAT currently requires that there are no more than one Primary body per Force Model but this behavior will change in future versions and the user interface is designed to naturally support this future development area. 

 

GMAT currently requires that the PrimaryBody and the CentralBody be the same. When you set the PrimaryBody, the Central Body becomes read only in the GUI, and its value is set to the value of the primary body.  Changing the PrimaryBody to “None” enables selection of the Central Body.  When you select a Primary Body in the GUI, the Gravity and Drag fields activate and allow you to select models for those forces consistent with the body selected in the Primary Body field.  For example, if you select Earth as the Primary Body, you can only select Earth drag models in the Atmosphere Model field.  See the Field list above for available models. 

 

Configuring Gravitational Models

 

GMAT supports point mass gravity, spherical harmonic, and Earth tide models.  On a Propagator, all celestial bodies are classified into two mutually exclusive categories: Primary Bodies, and Point Masses. To model a body as a point mass, add it to the PointMasses list.  GMAT currently requires that there be only a single PrimaryBody.  When a primary body is selected,  the central body and primary body must be the same. 

 

Bodies modelled as point masses use the gravitational parameter defined on the body (i.e. Earth.Mu) in the equations of motion.  Bodies defined as primary bodies use the constants defined on the potential file in the equations of motion. GMAT supports two gravity file formats. the .cof format and the STK .grv format.  You can provide a custom potential file for your application as long as it is one of the supported formats.  Potential files defined in the startup file are available in the Model list in the GUI.  For example, the following lines in the startup file configure GMAT so that EGM96 is an available option for Model when PrimaryBody is Earth:

 

EARTH_POT_PATH                   = DATA_PATH/gravity/earth/

EGM96_FILE                       = EARTH_POT_PATH/EGM96.cof

 

Below is an example script snippet for configuring a custom gravity model including Earth tides.

Create ForceModel aForceModel;

aForceModel.CentralBody = Earth;

aForceModel.PrimaryBodies = {Earth};

aForceModel.GravityField.Earth.Degree = 21;

aForceModel.GravityField.Earth.Order  = 21;

aForceModel.GravityField.Earth.PotentialFile = 'c:\MyData\File.cof';

aForceModel.GravityField.Earth.EarthTideModel = 'SolidAndPole';

 

 

Configuring Drag Models

 

GMAT supports many density models for Earth including Jacchia-Roberts and various MSISE models. Density Models for non-Earth bodies -- the MarsGRAM model for example -- are included using custom plug-in components and are currently only supported in the script interface.

 

To configure Earth density models, select Earth as the PrimaryBody,  In the GUI, this activates the AtmosphereModel list.  You can configure the solar flux values using the Drag setup after you have selected an atmosphere model. Below is an example script snippet for configuring the NRLMSISE00 density model.

 

Create ForceModel aForceModel;

GMAT aForceModel.PrimaryBodies = {Earth};

GMAT aForceModel.Drag.AtmosphereModel = NRLMSISE00;

GMAT aForceModel.Drag.F107 = 145;

GMAT aForceModel.Drag.F107A = 160;

GMAT aForceModel.Drag.MagneticIndex = 4;

 

Note that when you select None for Drag.AtmosphereModel , the fields Drag.F107, Drag.F107A, and Drag.MagneticIndex are inactive and must be removed from your script file to avoid parsing errors.  When working in the GUI, this is performed automatically.

 

The table below describes the limits on altitude for drag models supported by GMAT. 

 

Model

Theoretical Attitude (h) Limits

Comments

MSISE86

90 < h < 1000

GMAT will not allow propagation below 90 km altitude.

MSISE90

0 < h <1000

GMAT will allow propagation below 0 km altitude but results are non-physical.

NRLMSISE00

0 < h <1000

GMAT will allow propagation below 0 km altitude but results are non-physical.

JacchiaRoberts

h > 100

GMAT will not allow propagation below 100 km altitude.

 

 

 

Caution: GMAT uses the original single precision FORTRAN code developed by the scientists who created the MSISE models.  At low altitudes, the single precision density can cause numeric issues in the double precision integrator step size control and integration can be unacceptably slow.  You can avoid the performance issue by using either fixed step integration or by using a relatively high Accuracy value such as 1e-8.  You may need to experiment with the Accuracy setting to find a acceptable for your application.

 

 

 

Configuring an SRP Model

 

GMAT uses a dual cone model to model central body shadowing of the spacecraft and

models solar radiation pressure using a spherical spacecraft model.  You can define the solar flux using two approaches which are currently only supported in the script interface.   One approach is to define the flux value using the SRP.Flux field and the value of an astronomical unit (in km) using the Nominal_Sun field as shown in the following example.  

Create ForceModel aForceModel;

GMAT aForceModel.PrimaryBodies = {Earth};

GMAT aForceModel.SRP = On;

GMAT aForceModel.SRP.Flux = 1367;

GMAT aForceModel.SRP.Nominal_Sun = 149597870.691;

 

 

An alternative approach is to define the flux pressure at 1 astronomical unit using the Flux_Pressure field as shown below.

Create ForceModel aForceModel;

GMAT aForceModel.PrimaryBodies = {Earth};

GMAT aForceModel.SRP = On;

GMAT aForceModel.SRP.Flux_Pressure = 4.53443218374393e-006;

GMAT aForceModel.SRP.Nominal_Sun = 149597870.691;

 

 

If you mix flux settings, as shown in the example below, GMAT will use the last approach in the script.  Here, GMAT will use the Flux_Pressure setting.

Create ForceModel aForceModel;

GMAT aForceModel.PrimaryBodies = {Earth};

GMAT aForceModel.SRP = On;

GMAT aForceModel.SRP.Flux = 1370;

GMAT aForceModel.SRP.Nominal_Sun = 149597870;

GMAT aForceModel.SRP.Flux_Pressure = 4.53443218374393e-006;

 

 

Caution: GMAT’s default option for configuring solar flux for an SRP model is to use SRP.Flux and Nominal_Sun fields.  If you initially configured the Flux_Pressure field, when you save your mission via the GUI, GMAT will write out SRP.Flux and Nominal_Sun values consistent with your setting of  Flux_Pressure.

 

 

Variational Equations and the STM

 

GMAT can optionally propagate the orbit State Transition Matrix (STM).  For more information on how to configure GMAT to compute the STM, see the Propagate command section.

 

Caution: GMAT allows you to propagate the State Transition Matrix (STM) along with the orbital state.  However, not all variational terms are implemented for STM propagation.  The following are implemented: Point Mass Perturbation, Spherical harmonics (with tide models), and Solar Radiation Pressure.  The following are NOT implemented: Drag and Relativistic terms, and finite burns.

 

Additionally, the SRP variational term does not include the partial derivative of the percent shadow with respect to orbital state.   This approximation is acceptable for orbits with short penumbra durations but is inaccurate for orbits that spend relatively long periods of time in penumbra.

 

Examples

 

A Force Model for two-body propagation

Create Spacecraft aSat;

 

Create ForceModel aForceModel;

aForceModel.CentralBody = Earth;

aForceModel.PointMasses = {Earth};

 

Create Propagator aProp;

aProp.FM = aForceModel;

 

BeginMissionSequence

 

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

 

 

A Force Model for High Fidelity Low Earth Orbit Propagation

Create Spacecraft aSat;

 

Create ForceModel aForceModel;

aForceModel.CentralBody = Earth;

aForceModel.PrimaryBodies = {Earth};

aForceModel.PointMasses = {Sun, Luna};

aForceModel.SRP = On;

aForceModel.RelativisticCorrection = On;

aForceModel.ErrorControl = RSSStep;

aForceModel.GravityField.Earth.Degree = 20;

aForceModel.GravityField.Earth.Order = 20;

aForceModel.GravityField.Earth.PotentialFile = 'EGM96.cof';

aForceModel.GravityField.Earth.EarthTideModel = 'None';

aForceModel.Drag.AtmosphereModel = MSISE90;

aForceModel.Drag.F107 = 150;

aForceModel.Drag.F107A = 150;

aForceModel.Drag.MagneticIndex = 3;

aForceModel.SRP.Flux = 1359.388569998901;

aForceModel.SRP.Nominal_Sun = 149597870.691;

 

Create Propagator aProp;

aProp.FM = aForceModel;

 

BeginMissionSequence

 

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

 

 

A Force Model for High Fidelity Lunar Orbit Propagation

Create Spacecraft Moon;

GMAT Moon.DateFormat = UTCGregorian;

GMAT Moon.Epoch.UTCGregorian = 01 Jun 2004 12:00:00.000;

GMAT Moon.CoordinateSystem = MoonMJ2000Eq;

GMAT Moon.DisplayStateType = Cartesian;

GMAT Moon.X = -1486.792117191545200;

GMAT Moon.Y = 0.0;

GMAT Moon.Z = 1486.792117191543000;

GMAT Moon.VX = -0.142927729144255;

GMAT Moon.VY = -1.631407624437537;

GMAT Moon.VZ = 0.142927729144255;

 

Create CoordinateSystem MoonMJ2000Eq

MoonMJ2000Eq.Origin = Luna;

MoonMJ2000Eq.Axes   = MJ2000Eq;

 

Create ForceModel MoonLP165P;

GMAT MoonLP165P.CentralBody = Luna;

GMAT MoonLP165P.PrimaryBodies = {Luna};

GMAT MoonLP165P.SRP = On;

GMAT MoonLP165P.SRP.Flux = 1367;

GMAT MoonLP165P.SRP.Nominal_Sun = 149597870.691;

GMAT MoonLP165P.Gravity.Luna.PotentialFile = ../data/gravity/luna/LP165P.cof;

GMAT MoonLP165P.Gravity.Luna.Degree = 20;

GMAT MoonLP165P.Gravity.Luna.Order = 20;

 

Create Propagator RKV89;

GMAT RKV89.FM = MoonLP165P;

 

BeginMissionSequence

 

Propagate RKV89(Moon) {Moon.ElapsedSecs = 300};

 

 

Warnings/Errors

Open Issue: Need to include name of propagator and/or script line in the error messages below. 

 

 

If propagation includes STM and Drag is turned on:

Warning:  The orbit state transition matrix does not currently contain drag contributions.

 

If propagation includes STM and SRP is turned on:

Warning:  The orbit state transition matrix does not currently contain SRP contributions from shadow partial derivatives.

 

Open Issue: You can currently set a force model to have no PrimaryBodies or no PointMasses.  When you click OK, the following Error Message is thrown” Please select primary bodies or point mass bodies”.  I propose changing this to “A ForceModel must have at least one PrimaryBody or at least one PointMass body.  Please select a PrimaryBody or PointMass body.”

 

 

Test Considerations/Comments

 

Add limits on density models to the spec.

 

I have moved all of my test consideration items to the test procedures for this feature.  -SPH

 

Test Procedures

The test procedures for this feature were written before migrating to google docs and are too complex for google docs.  They are located here: SourceForge\trunk\doc\SystemDocs\Test\FRR-13DynamicsModelTestProceduresNew