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
3
that warning is seen.
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
2
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.
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)
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
Differential corrector
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/EndTarget
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
2
3
Per discussion with Steve H, field couplings for ApplyCorrections and ExitMode were
changed to ‘None.’
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)
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
Create
Create
Create
Create
Spacecraft aSat
Propagator aPropagator
Variable I
ImpulsiveBurn aBurn
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_Ta
rget_No_interpreter_exception
GMT-3127. Intepreter Error received:
Target_Validation_NonlinearConstraint
_Inside_Target_No_interpreter_excepti
on
GMT-3127. Intepreter Error received:
Target_Validation_Achieve_Inside_Opt
imize_No_interpreter_exception
GMT-3127. Intepreter Error received:
**** ERROR ****
Interpreter Exception: The Solver "DefaultDC" is not a(n) Optimizer in line:
*** ERROR ****
Interpreter Exception: The Solver "DefaultDC" is not a(n) Optimizer in line:
**** 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'.