Feature Spec and Test Procedures

 

 

Spec User’s Guide

Explore

Known Bugs

Failing Tests

Other Findings

Requirements

Interface/Functional Spec

Overview

Description

Fields

GUI

Remarks

Behavior When Changing the Coordinate System

Examples

Test Procedures

Assumptions

Existing Tests

Recommended Additional Tests

 

Spec User’s Guide

This section is for spec writers to explain how we write specs.  Assume for this release that this document will be used by software testers to test the software, and by technical writers to write end-user documentation.   When possible write the specifications so that content can be used with little or no modification in user-documentation and have therefore written the document as if the end-user is the reader.  The organization of the functional spec section is modelled after MATLAB’s help.  See existing GMAT example for the For command, Spacecraft Epoch, and Propagator for good examples of finished specifications.

 

General spec writing guidelines

      Follow all rules in the GMAT Style Guide .

      Use clear, simple, active voice

      Assume tech-writer/end-user are the primary audience for all material not contained in message boxes (see below).  i.e. (write with end-user quality material in main sections, use whatever is necessary to convey the point in message boxes).

      Read existing specs for example of style before writing

      See Force-Model for a rigorous Resource Example

      See Target for a rigorous Command example

      If you are a feature lead drafting a spec chapter, emphasize completeness of content.  The style does not have to be perfect, it will be reworked by the doc owner.

      If you are the PDL, focus on clarity and consistency of the text.  

      Here are special annotation styles

 

Open Issue:  Use a red table box like this to point out issues in behavior or functionality that are not resolved.  THESE ARE NOT BUGS!!  Must be resolved before spec is finished.

 

Caution:  Use a red table box to include potentially confusing or very important information for users.  Examples include when a feature only works in the script and not in the GUI, or if a feature can potentially be misused if the user does not understand something critical.

 

For GUI Tester:  Put information intended for a specific document user in a separate grey table box.  For example, if a feature may require a unique GUI test type, let the GUI tester know by including the information in a box like this. 

 

 

Put script snippets in a grey table box and use monospace font.

BeginFiniteBurn aFiniteBurn(aSat)

BeginFiniteBurn aFiniteBurn(aSat)

BeginFiniteBurn aFiniteBurn(aSat)

 

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!

Known Bugs

Known bugs committed in JIRA against this feature.

Failing Tests

Tests failing in the nightly regression reports related to this feature.

Other Findings

Issues you find when performing exploratory testing.

Requirements

 

Move requirements from formal SRS into a table below and delete this sentence.

 

These are working requirements.  They are included here for review and convenience purposes.  After review, requirements are maintained in the formal SRS located at SourceForge in /trunk/doc/SystemDocs/Requirements.  Send final requirements to CCB lead (SPH).

 

ID

Requirements

FRR-xyz

The requirement.

FRR-xyz.

The requirement

Interface/Functional Spec

n checklists :

List of Minor To-Do/Feature Cleanup Discussion

 

These are NOT major bugs and just simple to do list stuff.  We may just want to create a JIRA ticket for this.  This is an experiment.

Owner

Status

Done

djc

 

In script you can set MinStep = MaxStep.  In GUI, this throws an error.   Remove this validation test from the GUI.  We allow this setting at the user's risk in the script and so we should allow in the GUI also.  We implemented StopIfAccuracyIsViolated field for this reason.

djc

 

Hidden parameters on BulirschStoer Integrator appear to affect performance. We need find reasonable values for these and document what they do.  

djc

 

ABM integrator field names are different in GUI and script.  The Input Range error message also uses the GUI syntax. Rename in the GUI and change error message syntax.  Changing label shouldn't change the text box name for Test Complete.

djc

 

InitialStepSize field does not use standard input range error message for invalid data. Set to zero to see this behavior.

djc

 

Ranges for some fields such as accuracy accept values arbitrarily close to "bad" values.   For example,  BS Integrator crashes if Accuracy = 20 for example.  I think we should put some common sense range values on selected integrator parameters.  

djc

 

Are there any special range checks required for BS fields?

 

 

Open Issue for DJC.: Need help documenting the following parameters on BulirschStoer integrator called :

 

GMAT BulStoerProp.MinimumReduction = 0.0007;

GMAT BulStoerProp.MaximumReduction = 1e-008;

GMAT BulStoerProp.MinimumTolerance = 1e-012;

 

I have no idea what these do.  Can you fill out the field spec entries for range and description.  You will need to define ranges for these fields!!!

 

Open Issue for DJC:: We may have old integrator names like DormandElMikawy... in our enumerations.   Can you add all accepted enumerations for the integrator Type enumeration below so I (SPH) can decide what to do?

 

 

Requirements

These are here for review purposes only and will be migrated to formal SRS when complete.

FRR-14.1.0

The system shall support the following embedded Runge-Kutta integrators:

FRR-14.1.1

1)      Runge Kutta Verner (89)

FRR-14.1.2

2)      Runge-Kutta Nystrom (68)

FRR-14.1.3

3)      Runge-Kutta Fehlberg (56)

FRR-14.1.4

4)      Prince-Dormand (45)

FRR-14.1.5

5)      Prince-Dormand (78)

FRR-14.2

The system shall support the Bulirsch-Stoer integrator.

FRR-14.3

The system shall support the Adams-Bashforth-Moulton integrator.

FRR-14.4.0

The system shall allow the user to set the following properties for all integrators:

FRR-14.4.1

1)      Initial step size

FRR-14.4.2

2)      Accuracy

FRR-14.4.3

3)      Min step size

FRR-14.4.4

4)      Max step size

FRR-14.4.5

5)      Max step attempts

FRR-14.5.0

The system shall allow the user to set the following additional settings for the Adams-Bashforth-Moulton method:

FRR-14.5.1

1)      Minimum/Lower integration error

FRR-14.5.2

2)      Target integration error

FRR-14.6.0

The system shall support the following modes for step size error control:

FRR-14.6.1

1)      Root Sum Square of the error compared to integration step

FRR-14.6.2

2)      Root Sum Square of the error compared to the state vector

FRR-14.6.3

3)     L1 Norm of error compared to step

FRR-14.6.4

4)     L1 Norm of error compared to state

FRR-14.6.5

5)      None (fixed step)

FRR-14.6.6

The system shall provide a flag to optionally stop integration if accuracy cannot be satisfied.

FRR-14.7.0

The system shall allow the user to set the following additional settings for the Bulirsch Stoer method:

FRR-14.7.1

1)  Minimum Reduction Safety Coefficient

FRR-14.7.2

2)  Maximum Reduction Safety Coefficient

Propagator Spec

Overview

 

A propagator models spacecraft motion.

Description

 

A Propagator is the GMAT component used to model spacecraft motion. GMAT contains two types of propagators: a numerical integrator type, and an ephemeris type. When using a numerical integrator type propagator, you can choose among a suite of numerical integrators implenting Runge-Kutta and predictor corrector methods as well the Bulirsch-Stoer integrator. See the Remarks section below for detailed discussion of GMAT’s numerical integrators as well as performance and accuracy comparisons, and usage recommendations.

 

A  Propagator object that uses a numerical integrator (as opposed to an ephemeris propagator) is one of a few objects in GMAT that is configured differently in the scripting and in the GUI.  In the GUI, you configure the integrator and force model setting on the same dialog box. When working in the script, you must create a ForceModel object separately from the Propagator and specify the force model using the “FM” field on the propagator. See examples later in this section for details.

 

The ephemeris based propagator is turned off in the GMAT installation because final testing is not complete. Later in this section, we describe how to enable the SPICE propagator and show a brief example that uses it.

 

See Also : Force Model, Propagate command.

Fields

 

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

For user doc writers: There are about 7 fields used by all integrators, 2 additional fields only for ABM,  and 3 that are used only by the Bulirsch-Stoer integrator.  The tables in the reference guide needs to make this clear. One option is to have two tables, the first states the parameters that are available for all integrators, the second table states the parameters that are only for the Bulirsh-Stoer integrator.

 

GUI

 

Settings for the embedded Runge-Kutta integrators and the Bulirsch Stoer Integrators:

 

The Adams-Bashforth-Moulton integrator has additional settings, as shown below:

 

For Developers: When changing the Type field, all fields should set back to their default values.  This is done because settings that may be acceptable for one integrator may be poor for another and the defaults are “reasonable” for all integrators.

 

For Testers: We do not allow users to clone a Propagator because some redesign work is required for this to work consistently.

Remarks

 

Best Practices for Using Numerical Integrators

 

We recommend that you study the performance and accuracy analysis documented later in this section to select a numerical integrator for your application.  You may need to perform further analysis and comparisons for your application.  The comparison data below suggest that the PrinceDormand78 integrator is the best all purpose integrator in GMAT.  When in doubt, use the PrinceDormance78 integrator, and set MinStep to zero so that the integrator’s adaptive step algorithm controls the minimum integration step size. 

 

Below are some important comments on GMAT’s step size control algorithms and the dangers of using a non-zero value for the minimum integration step size.

 

Caution: GMAT’s default error computation mode is RSStep and this is a more stringent error control method than RSSState that is often used as the default in other software such as STK.  If you set Accuracy to a very small number, 1e-13 for example, and leave ErrorControl set to RSSStep, integrator performance will be poor, for little if any improvement in the accuracy of the orbit integration. 

 

To find the best balance between integration accuracy and performance, we recommend you experiment with the accuracy setting for your selected integrator for your application. You can start with a relatively high setting of Accuracy, say 1e-9, and lower the accuracy by an order of magnitude at a time and compare the final orbital states to determine where smaller values of Accuracy result in longer propagation times without providing more accurate orbital solutions.

 

Caution: GMAT allows you to set a Minimum Step on numerical integrators.  It is possible that the requested Accuracy cannot be achieved given the MinimumStep setting.  The Propagator flag StopIfAccuracyIsViolated determines the behavior if Accuracy cannot be satisfied.  If StopIfAccuracyIsViolated is true, GMAT will throw an error and stop execution if integration accuracy is not satisfied.  If StopIfAccuracyIsViolated is false, GMAT will only throw a warning that the integration accuracy was not satisfied but will continue to propagate the orbit.

 

Numerical Integrators Overview

 

The table below describes each numerical integrator in detail.

Integrator Name

Description

RungeKutta89

An adaptive step, ninth order Runge-Kutta integrator with eighth order error control. The coefficients were derived by J. Verner. Verner developed several sets of coefficients for an 89 integrator and we have chosen the coefficients that are the most robust but not necessarily the most efficient.

PrinceDormand78

An adaptive step, eighth order Runge-Kutta integrator with seventh order error control. The coefficients were derived by Prince and Dormand.

PrinceDormand45

An adaptive step, fifth order Runge-Kutta integrator with fourth order error control. The coefficients were derived by Prince and Dormand.

RungeKutta68

A second order Runge-Kutta-Nystrom type integrator with coefficients developed by by Dormand, El-Mikkawy and Prince. The integrator is a 9-stage Nystrom integrator, with error control on both the dependent variables and their derivatives. This second order implementation will correctly integrate forces that are non-conservative but it is not recommended for this use.  See the integrator comparisons below for numerical comparisons.  You cannot use this integrator to integrate mass during a finite maneuver because the mass flow rate is a first order differential equation not supported by this integrator.

RungeKutta56

An adaptive step, sixth order Runge-Kutta integrator with fifth order error control. The coefficients were derived by E. Fehlberg.

BulirschStoer

A Gragg-Bulirsch-Stoer integrator as described in Numerical Recipes in C. The basic algorithm uses a modified-midpoint algorithm, evaluated at intermediate points in the interval of interest, to extrapolate the next state vector from the current state. This extrapolation is performed for several different sizes of substeps, and the resulting states are used to estimate the results as the step size of the substeps is reduced to zero.

 

This integrator can take large steps that may be undesirable for graphical output or when high precision, dense spacecraft ephemerides are required. The Bulirsch-Stoer integrator is best used for long propagations required for lifetime and re-entry analysis.

AdamsBashforthMoulton

A fourth-order Adams-Bashford predictor / Adams-Moulton corrector as described in Fundamentals of Astrodynamics by Bate, Mueller and White. The predictor step extrapolates the next state of the variables using the the derivative information at the current state and three previous states of the variables. The corrector uses derivative information evaluated for this state, along with the derivative information at the original state and two preceding states, to tune this state, giving the final, corrected state. The ABM integrator uses and the RungeKutta89 integrator to start the integration process.  The ABM is a low order integrator and should not be used for precise applications or for highly nonlinear applications such as celestial body flybys. 

 

 

Performance & Accuracy Comparison of Numerical Integrators

 

This table below shows performance and accuracy comparisons of numerical integrators for different orbit types. Performance is normalized and is shown in seconds and accuracy is given in meters. 

 

 

 

LEO

HEO

Lunar Tran

Mars Tran

Finite Thrust (blow down tank)

Finite Thrust (Pressure regulated tank)

PrinceDormand78

Perf

(sec)

1.466

1.000

2.932

1.000

1.000

1.000

 

Diff (m)

0.0031

0.0085

 

0.00024

0.0740

0.00160

0.0070

PrinceDormand45

Perf (sec)

2.862

2.0454

3.670

1.1930

1.2657

1.488

 

Diff (m)

0.0010

0.0344

0.00226

0.1484

0.0022

0.002

RungeKutta89

Perf  (sec)

1.470

1.1071

1.000

1.0173

1.0259

1.0507

 

Diff (m)

0.0049

0.0132

0.0633

0.0070

0.0019

0.00057

RungeKutta68

Perf (sec)

1.000

1.086

1.040

1.026

TBD

TBD

 

Diff (m)

64.025

0.600

0.0167

0.0074

TBD

TBD

RungeKutta56

Perf sec)

2.173

1.4073

3.030

1.0770

1.1665

1.2680

 

Diff (m)

0.0223

0.0538

0.0023

0.1273

0.0060

0.00230

Bulirsch Stoer

Perf (sec)

TBD

TBD

TBD

TBD

TBD

TBD

 

Diff (m)

TBD

TBD

TBD

TBD

TBD

TBD

Adams-Bashforth-Moulton

perf (sec)

3.540

4.483

6.510

1.888

1.707

1.7034

 

Diff (m)

0.0113

1.755

0.1023

20.224

0.00005

0.0025

 

Fields Unique to the AdamsBashforthMoulton Integrator

 

The Adams-Bashforth-Moulton integrator has two additional fields named TargetError and LowerError that are only active when Type is set to AdamsBashforthMoulton.  If you are using another integrator type, those fields must be removed from your script file to avoid parsing errors.  When working in the GUI, this is performed automatically.  See examples below for more details.

 

Fields Unique to the  BulirschStoer Integrator

 

The Bulirsh-Stoer integrator has additional fields named MinimumReduction, MaximumReduction, and MinimumTolerance that are only active when Type is set to BulirschStoer.  Note these fields are only available in the script.  Furthermore, If you are using another integrator type, those fields must be removed from your script file to avoid parsing errors.  When working in the GUI, this is performed automatically.  See examples below for more details.

Examples

 

Propagate an orbit using a general purpose Runge-Kutta integrator.

Create Spacecraft aSat;

Create ForceModel aForceModel;

 

Create Propagator aProp;

aProp.FM                        = aForceModel;

aProp.Type                      = PrinceDormand78;

aProp.InitialStepSize   = 60;

aProp.Accuracy                  = 1e-011;

aProp.MinStep                   = 0;

aProp.MaxStep                   = 86400;

aProp.MaxStepAttempts = 50;

aProp.StopIfAccuracyIsViolated = true;

 

BeginMissionSequence

 

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

 

 

Propagate an orbit using an Adams-Bashforth-Moulton predictor-corrector integrator.

Create Spacecraft aSat;

Create ForceModel aForceModel;

aForceModel.ErrorControl = RSSStep;

 

Create Propagator aProp;

aProp.FM                        = aForceModel;

aProp.Type                      = AdamsBashforthMoulton;

aProp.InitialStepSize   = 60;

aProp.MinStep                   = 0;

aProp.MaxStep                   = 86400;

aProp.MaxStepAttempts   = 50;

%  Note the following fields must be set with decreasing values!

aProp.Accuracy                  = 1e-010;

aProp.TargetError               = 1e-011;

aProp.LowerError                = 1e-013;

aProp.StopIfAccuracyIsViolated = true;

 

BeginMissionSequence

 

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

 

 

Propagate an orbit using the Bulirsch-Stoer integrator. 

Create Spacecraft aSat;

Create ForceModel aForceModel;

 

Create Propagator aProp;

aProp.FM                        = aForceModel;

aProp.Type                      = BulirschStoer;

aProp.InitialStepSize   = 60;

aProp.MinStep                   = 0;

aProp.MaxStep                   = 86400;

aProp.MaxStepAttempts   = 50;

aProp.Accuracy                  = 1e-011;

aProp.MinimumReduction = 0.7;

aProp.MaximumReduction = 1e-005;

aProp.MinimumTolerance = 1e-012;

aProp.StopIfAccuracyIsViolated = true;

 

BeginMissionSequence

 

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

 

Propagate using a fixed step configuration.  Do this by setting InitialStepSize to the desired fixed step size and setting ErrorControl to None.  This example propagates in constant steps of 30 seconds.

 

Create Spacecraft aSat;

Create ForceModel aForceModel;

aForceModel.ErrorControl = None;

 

Create Propagator aProp;

aProp.FM                        = aForceModel;

aProp.Type                      = PrinceDormand78;

aProp.InitialStepSize = 30;

 

BeginMissionSequence

 

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

Test Procedures

Assumptions

 

      These procedures test integrators for many trajectory types and force model types.

      All dynamics model types including finite thrust

      Circular, Hyperbolic, and Highly Elliptic orbits

      Forward and backwards propagation

      Basic integrator settings such as max step, etc are tested using two-body force model with semi-analytic solution as truth data.

      Stopping condition tests will be performed when testing propagate command.

 

Nominal Tests

Nominal tests are broken down by flight regime/dynamics model tests and integrator settings tests.

Integrator/Flight Regime Tests

These tests are written such that forward propagation occurs for some “reasonable” duration, then backwards propagation occurs back to the initial epoch.  Two comparisons are made to ensure the integrator performs correctly.  The first test compares forward integrated results with truth data at the end time of forward propagation.  The second test compares backwards integrated results with the initial state.  The objective of these cases is to test forward and backward propagation for all integrators using

      different trajectory regimes: Circular, Highly Elliptic, Hyperbolic

      different force models:  Harmonic Gravity, Drag, SRP, Point Mass, Finite Thrust

Priority

Status

Summary

P1

Done

RHQ

Test all integrators for ISS orbit by modifying this script: GMAT_ISS_EarthSunLuna_EGM96_MSISE90_SRP_SolidAndPoleTide.script

P1

Done

RHQ

Test all integrators for Molniya orbit by modifying this script: GMAT_Molniya_EarthSunLuna_JGM2_JR_SRP

P1

Done

RHQ

Test all integrators for Lunar transfer by modifying this script: GMAT_LunarTransfer_AllPlanets_DE421

P1

Done

RHQ

Test all integrators using Mars transfer orbit with Full model: GMAT_MarsTransfer_4  (“Full Field” model for each body)

P1

Done

RHQ

Test all integrators for finite burn with blow-down tank: Thruster_FBurn_Earth_ScA_ThrusterB_CS3_TankL

P1

Done

RHQ

Test all integrators for finite burn with pressure regulated tank: Thruster_FBurn_Earth_ScA_ThrusterB_CS2_TankA

Integrator Settings Tests

 

The objective of these tests it is to test integrator settings such as MinStep and MaxStep for example.  The tests primarily use a common two-body orbit with analytic solution to the two-body problem as truth data.  Note that some settings cannot be explicitly tested from an end-user perspective.  For example, to test Accuracy, we start with a loose accuracy setting (1e-7) and compare to truth, then try 1e-9 and compare to truth and see if the results are closer to truth for the smaller value of accuracies. Note:  I am assuming we leave in fields specific to BS integrator and therefore need additional tests for them.

 

Google docs sucks for this:

Priority

Status

Summary

P1

Done

RHQ

Test InitialStepSize by setting to non-default and set ErrorControl to RSSStep. Verify that first step occurs at the size of InitialStepSize.

P1

Done

RHQ

MaxStep for all integrators.

P1

Done

RHQ

MinStep for all integrators.

P1

Done

RHQ

Accuracy for all integrator.

P1

Done

RHQ

MaxStepAttempts

P1

Done

RHQ

StopIfAccuracyIsViolated

P1

Done

RHQ

LowerError

P1

Done

RHQ

TargetError

P1

Done

RHQ

MinimumReduction

P1

Done

RHQ

MaximumReduction

Edge/Corner/Miscellaneous Tests

Can’t think of any.  Perhaps special tests for the ABM startup algorithm?

Priority

Status

Summary

 

 

 

 

 

 

 

 

 

Unique Validation Tests

These are unique validation tests that are required for special field or object couplings for this feature.

Priority

Status

Summary

P1

RHQ

Done

Test range constraints on the AdamsBashForthMoulton accuracy settings:               0 < LowerError < TargetError < Accuracy

P1

RHQ

Done

Test step size range constraints.  MinStep <= MaxStep.

P1

RHQ

Done

Test that Error is thrown deprecating mass using second order integrator.

P1

RHQ

Done

Test that fields for ABM are not available for other integrators

P1

RHQ

Done

Test that fields available for BS are not available for other integrators

Unique Mode Tests

These are no unique mode tests for this object.

Priority

Status

Summary

 

 

 

 

 

 

 

 

 

Unique GUI Tests

These are tests that are unique to the GUI interface for this feature that are not covered by the standard GUI test template and procedures.

Priority

Status

Summary

P1

SJH

Done

Test that ABM fields appear when switching to ABM integrator

P1

SJH

Done

Test that defaults reset when integrator type is changed.