Target

Feature Spec and Test Procedures

Lead:  Steve C

Developer:  Darrel

STE/GUI Tester:  Tom

 

Explore

Failing Tests

Other Findings

Requirements

Interface/Functional Spec

Overview

Script Syntax

Description

Fields

GUI

Remarks

Examples

Test Procedures

Assumptions

Existing Tests

Recommended Additional Tests

Appendix A - Miscellaneous Data

Explanation of GMT-2332

NOTES

 

Explore

 

Known bugs/issues committed in JIRA against this feature:

 

JIRA ID

Summary

Comment

GMT-2332

Apply Corrections Doesn't work if initial guess is set to a spacecraft parameter

See Appendix for explanation. 

1         Added explanation note to the documentation.

2         GMAT should throw a warning.  Shawn will add a test to verify that warning is seen. 

3         Still Open as of 11/27/12.  Assigned to SPH. 

 

 

 

Note that GMT-2637 is the Target QA task (not a bug).  

 

Failing Tests

No failing tests. 

 

Run Identification:  [Gmat-buildtest] Test results: 2012-09-12 (Win7-64/GMAT-32/M2010a/VS)

 

Other Findings

 

1         Submitted bug, GMT-3127 , Interpreter does not catch case where Minimize command is embedded in a Target sequence.  Resolution:  Added regression tests.  Issue closed 11/21/12.

2         Submitted bug, GMT-3130 , Confusing message when solver employs maximum number of iterations Status as of 11/21/12:  Assigned to SPH to get comment on case when using fmincon solver. 

Requirements

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. 

 

 

ID

Requirement

FRC-3.1

The system shall allow a user to define the beginning of a target sequence by issuing a Target command.

FRC-3.2

The system shall allow a user to define the end of a Target sequence by issuing an EndTarget command.

FRC-3.3

The system shall support all GMAT commands internal to a target sequence.

FRC-3.4

The system shall allow users to specify multiple control variables in a single targeting sequence using the Vary command as described in FRC-2.

FRC-3.5

The system shall allow users to specify multiple targeting constraints using the Achieve command as described in FRC-5.

FRC-3.6.0

The system shall allow the user to select from the following solvers for a target sequence:

FRC-3.6.1

1)                Differential corrector

FRC-3.7.0

The system shall allow the user to select from the following modes when using the Target command:

FRC-3.7.1

1)                Run initial guess only

FRC-3.7.2

2)                Solve the differential correction problem

FRC-3.8.0

The system shall allow the user to select from the following exit mode options when a Target sequence has completed:

FRC-3.8.1

1)                Discard and continue.  (does not save the solution)

FRC-3.8.2

2)                Save and continue (saves solution to the initial guess values)

FRC-3.8.3

3)                Stop the GMAT run.

FRC-3.9

The GUI interface shall allow the user to apply corrections

 

Note that, as shown in the field spec, there is no script command for ‘apply corrections.’

Interface/Functional Spec

Overview

Solve for condition(s) by varying one or more parameters to achieve one or more goal(s).

Script Syntax

Target SolverName [ { [ SolveMode = value ] , [ ExitMode = value ] } ]

Vary command …

script statement

Achieve command …

EndTarget

Note: See the Remarks and Description for this complex command. Multiple Vary and Achieve commands are permitted and script statements can appear anywhere in the Target sequence.

 

Description

 

The Target and EndTarget commands are used to define a “Target Sequence” to determine, for example, the maneuver components required to raise orbit apogee to 42164 km. Another common targeting example is to determine the parking orbit orientation required to align a lunar transfer orbit with the moon. Target sequences in GMAT are general and these are just examples. Let’s define the quantities that you don’t know precisely but need to determine as the Control Variables. Define the conditions that must be satisfied as the Goals (sometimes called constraints) . A target sequence numerically solves a boundary value problem to determine the value of the Control Variables required satisfying the Goals. You define your control variables by using Vary commands and you define the problem constraints using Achieve commands. The Target/EndTarge t sequence is an advanced command. The examples later in this section give a more detailed explanation.

 

See Also: DifferentialCorrector , Optimize

Fields

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

 

Notes to team only (not for inclusion in documentation)

 

1         Per discussion with Steve H, field couplings for ApplyCorrections and ExitMode were changed to ‘None.’

2         Some commands come in pairs such as Target and EndTarget.  Per discussion with Steve H, the EndTarget command will be included in the field spec.  ( My Proposal is to put N/A when a column doesn’t apply to these “single-word” commands, but the description field should explain that the command is required to close the branch and show a coupling with the parent command)

3         The Target command, in effect, has an optional input used to give the Targeter a name.  Per discussion with Steve H, for simplicity, we choose not to include this in the field spec. 

a         Default Target script created

Target DC1 {SolveMode = Solve, ExitMode = DiscardAndContinue};

b         Named target sequence script created

Target 'Raise Apogee' DC1 {SolveMode = Solve, ExitMode = SaveAndContinue};

 

GUI

 

The Target command allows you to use a differential correction process to solve problems.  To solve a given problem, you need to create a so-called Target Sequence which we now define.  When you add a Target command to the mission sequence, an EndTarget command is automatically added as shown below.

 

 

In the example above, the Target command sequence is defined as all of the commands between the Target1 and End Target1 commands, inclusive.  Although not shown above, a Target command sequence must contain both a Vary command and an Achieve command.  The Vary command is used to define the control variables which can be varied in order to achieve a certain goal.  The Achieve command is used to define the desired goal.  In order for the Target Sequence to be well formed, there must be at least one Vary command before any Achieve commands, so that the variable defined in the Vary command can affect the goal specified in the subsequent Achieve commands.

 

Double click on Target1 command above to bring up the Target command dialog box, shown below, which allows you to specify your choice of Targeter (i.e., your choice of differential corrector), Solver Mode, and Exit Mode.  As described in the Remarks section, the Target command dialog box also allows you to apply corrections to your Target command sequence. 

 

 

Remarks

 

Content of a Target/EndTarget sequence

A Target/EndTarget sequence must contain at least one Vary command and at least one Achieve Command. See the Vary and Achieve command sections for details on the syntax for those commands. The First Vary command must occur before the first Achieve command. Target commands must be be coupled with one and only one EndTarget command. Each Target command field in the curly braces is optional. You can omit the entire list and the curly braces and the default values will be used for Target configuration fields such as SolveMode and ExitMode.

 

Use of a Target/EndTarget sequence

GMAT Target sequences can solve square problems (the number of Control Variables equals the number of constraints), over-determined problems (the number of Control Variables is less than the number of constraints) and under-determined problems (the number of Control Variables is greater than the number of constraints). In any of these cases, there may not be a solution and the type of solution found depends on the selection of the targeter (currently, only differential correctors are supported). Assuming a solution to the problem exists and assuming certain mathematical conditions are satisfied, there is often one solution for a square problem and many solutions to an under-determined problem. Problems with more goals (i.e., constraints) than variables may not have a solution. If your problem is under-determined, consider using an Optimize sequence to find an optimal solution in the space of feasible solutions.

 

Caution: If you configure a Target sequence and get the error “Error inverting the Differential Corrector Jacobian; it appears that the variables in the Vary command(s) do not affect the target parameters in the Achieve command(s)”, then your Control Variables defined in the Vary commands do not affect the Constraints defined in the Achieve commands. A common mistake in this case is that you forgot to apply a maneuver or that you specified the constraint before specifying a variable that affects that constraint.

 

Note on Using Apply Corrections

 

After the Target sequence has been run, you may choose to apply corrections by navigating to the Mission tree, right-clicking the Target command to bring up the Target window, and clicking the Apply Corrections button.  The ApplyCorrections button replaces the initial guess values specified in the Vary commands. If the Target sequence converged, the converged values are applied.  If the Target sequence did not converge, the last calculated values are applied.  Note that the ApplyCorrections feature is only currently available through the GUI interface. 

 

There is one situation where the action specified above, where the initial guess values specified in the Vary commands are replaced, does not occur.  This happens, as illustrated in the example below, when the initial guess value specified in the Vary command is given by a variable.  In this situation, the Apply Corrections button has no affect since GMAT does not allow variables to be overwritten. 

 

Create Variable InitialGuess_BurnDuration BurnDuration

Create DifferentialCorrector aDC

BeginMissionSequence

Target aDC

Vary aDC(BurnDuration = InitialGuess_BurnDuration);

Achieve aDC(BurnDuration = 10) % atypical Achieve command for

                               % illustrative purposes only

EndTarget

 

 

 

Command Interactions 

                  

Vary command 

Every Target sequence must contain at least one Vary command.  Vary commands are used to define the control variables associated with a Target sequence. 

Achieve command  

Every Target sequence must contain at least one Achieve command.  Achieve commands are used to define the goals associated with a Target Sequence. 

 

Examples

 

Use a Target sequence to solve for a root of an algebraic equation. Here we provide an initial guess of 5 for the Control Variable (or independent variable) x, and solve for the value of x that satisfies the Constraint y = 0, where  y := 3*x^3 + 2*x^2 - 4*x + 8. After executing this example you can look in the message window to see the solution for the variable x.  You can easily check that the value obtained does indeed satisfy the constraint.

Create Variable x y

Create DifferentialCorrector aDC

BeginMissionSequence

Target aDC

Vary aDC(x = 5)

y = 3*x^3 + 2*x^2 - 4*x + 8

Achieve aDC(y = 0,{Tolerance = 0.0000001})

EndTarget

 

 

Use a Target sequence to raise orbit apogee. Here the control variable is the velocity component of an ImpulsiveBurn object. The Constraint is that the position vector magnitude at orbit apogee is 42164.

Create Spacecraft aSat

Create Propagator aPropagator

Create Variable I

Create ImpulsiveBurn aBurn

Create DifferentialCorrector aDC

 

Create OrbitView EarthView

EarthView.Add = {Earth, aSat}

EarthView.ViewScaleFactor = 5

 

BeginMissionSequence

 

Target aDC

Vary aDC(aBurn.Element1 = 1.0, {Upper = 3})

Maneuver aBurn(aSat)

Propagate aPropagator(aSat, {aSat.Apoapsis})

Achieve aDC(aSat.RMAG = 42164)

EndTarget

 

Similar to the previous example, we  use a Target sequence to raise orbit apogee except that this time we use a finite burn.  Here the control variable is the duration of the Velocity component of a FiniteBurn object. The Constraint is that the position vector magnitude at orbit apogee is 12000.  Additional detail on the example below can be found in the Target Finite Burn to Raise Apogee tutorial.

 

Create Spacecraft DefaultSC;

Create Propagator DefaultProp;

Create Thruster Thruster1;

GMAT Thruster1.C1 = 1000;

GMAT Thruster1.DecrementMass = true;

Create FuelTank FuelTank1;

GMAT Thruster1.Tank = {FuelTank1};

Create FiniteBurn FiniteBurn1;

GMAT FiniteBurn1.Thrusters = {Thruster1};

GMAT DefaultSC.Tanks = {FuelTank1};

GMAT DefaultSC.Thrusters = {Thruster1};

Create Variable BurnDuration;

Create DifferentialCorrector DC1;

 

BeginMissionSequence;

 

Propagate DefaultProp(DefaultSC) {DefaultSC.Earth.Periapsis};

Target DC1;

Vary DC1(BurnDuration = 200, {Upper = 10000});

BeginFiniteBurn FiniteBurn1(DefaultSC);

Propagate DefaultProp(DefaultSC){DefaultSC.ElapsedSecs=BurnDuration};

EndFiniteBurn FiniteBurn1(DefaultSC);

Propagate DefaultProp(DefaultSC) {DefaultSC.Earth.Apoapsis};

Achieve DC1(DefaultSC.Earth.RMAG = 12000);

EndTarget;

Test Procedures

Assumptions

None.

Existing Tests

There are 34 files of the form *.tc. 

 

Test Name

Description

Target_DC_*.tc

 

 

There are 23 files of this type.  (16 of type Target_DC_Command_*.tc, 3 of type Target_DC_ExitMode_*.tc, 4 of type Target_DC_SolverMode_*.tc)

TargeterNesting.tc

 

*validation*.tc

Validation type tests.  There are 10 tests of this type. 

 

 

According to the table above, there are

23 + 1 + 10 = 34

files accounted for which agrees with the known number of test cases. 

Recommended Additional Tests

             

 

Unique Validation

Test Name

Summary

Target_Validation_Minimize_Inside_Target_No_interpreter_exception

GMT-3127 .  Intepreter Error received:  **** ERROR **** Interpreter Exception: The Solver "DefaultDC" is not a(n) Optimizer in line:

Target_Validation_NonlinearConstraint_Inside_Target_No_interpreter_exception

GMT-3127 .  Intepreter Error received:  *** ERROR **** Interpreter Exception: The Solver "DefaultDC" is not a(n) Optimizer in line:

Target_Validation_Achieve_Inside_Optimize_No_interpreter_exception

GMT-3127 .  Intepreter Error received:  **** ERROR **** Interpreter Exception: The Solver "DefaultSQP" is not a(n) DifferentialCorrector in line:

 

 

 

 

 

 

 

Target_DC_Max_Iterations_Display

GMT-3130 .  See also two tests added for this bug in Optimize feature group.

 

 

 

 

Appendix A - Miscellaneous Data

Note that this data is primarily for the internal use of the feature lead.  It does not need to be reviewed by the SDE and STE.  

Explanation of GMT-2332

 

Suppose you have a command such as

Vary 'Vary Burn Duration' DC1(BurnDuration = InitialGuess, {Perturbation = 0.0001, Lower = 0.0, Upper = 10000, MaxStep = 100, AdditiveScaleFactor = 0.0, MultiplicativeScaleFactor = 1.0});

 

Then you run the DC to convergence.  If you then go to the Mission sequence, double click on the target command, and click “Apply Corrections,” GMAT will not replace the variable InitialGuess with a number.  This is by design. 

 

NOTES

 

1         For the test, Target_DC_Max_Iterations_Display, i tried to do a LogTextComparator type test with the truth file containing the line, Targeting did not converge in 25 iterations.  The test did not pass.  See below.  I think it failed since when I created the truth file, I used the windows function, Create new text file.  When I copied an existing truth file and changed the name, it worked. 

 

These tests cause test system errors:

Target_DC_Max_Iterations_Display (script/truth)

Comparator LogTextComparator failed: Undefined function or method 'regexprep' for input arguments of type 'double'.