Optimize Command
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-3114
Show cost function value in message
window during optimization
Added regression tests. Issue closed
11/20/12.
Note that GMT-2642 is the Optimize QA task (not a bug).
Failing Tests
Run Identification: [Gmat-buildtest] Test results: 2012-10-22 (Win7-64/GMAT-32/M2010a/VS)
These tests have script errors that caused a failure:
Optimize_fmincon_SolveMode_Defaultscript
Comments/Actions Taken
● Test passed locally (11/20/12 build). May have been intermittent status-1 bug.
Other Findings
1
2
3
Submitted bug, GMT-3214, Message window, for Fmincon use, does not display converged
status. See FRR-20 fmincon Optimizer resource feature spec for resolution.
It is possible for an Optimization sequence to be defined and run without error and
containing neither a NonlinearContraint command nor a Minimize command. Submitted
bug, GMT-3216, Optimization sequence Contents.
■ Create FminconOptimizer SQP1;
SQP1.MaximumIterations = 50;
Create Variable x y Circle
BeginMissionSequence;
Optimize SQP1;
Vary SQP1(x = 1);
Vary SQP1(y = 1);
Circle = x*x + y*y
%NonlinearConstraint SQP1(Circle = 1);
%Minimize SQP1(y);
EndOptimize;
■ Resolution: Added regression tests. Issue closed 11/20/12.
Two regression added for this feature group for GMT-3130. Status: Assigned to SPH
11/21/12 for comment on fmincon case.
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-1.1
The system shall allow a user to define the
beginning of an optimization sequence by
issuing an Optimize command.
FRC-1.2
The system shall allow a user to define the
end of an optimization sequence by issuing an
EndOptimize command.
FRC-1.3
The system shall support all GMAT
commands internal to an optimization
sequence.
FRC-1.4
The system shall allow users to specify
control variables using the Vary command as
defined in FRC-2.
FRC-1.5
The system shall allow users to specify nonlinear constraints inside of an Optimize
sequence using the NonlinearConstraint
command defined in FRR-7.
FRC-1.6
The system shall allow the user to specify the
cost function in an optimization sequence
using the Minimize command defined in FRR6.
FRC-1.7
The system shall support multiple control
variables (Vary Commands) in an optimization
sequence.
FRC-1.8
The system shall support zero or more
nonlinear constraints in an optimization
sequence.
FRC-1.9
The system shall support at most one
minimize command in an optimization
sequence.
FRC-1.10.0
The system shall allow the user to select from
the following optimizers in an optimization
sequence if the libraries are available to the
user:
FRC-1.10.1
1)
Vf13ad
FRC-1.10.2
2)
fmincon
FRC-1.11.0
The system shall allow the user to select from
the following optimization modes when using
the optimize command:
FRC-1.11.1
1)
Run initial guess only
FRC-1.11.2
2)
Solve the optimization problem
FRC-1.12.0
The system shall allow the user to select from
the following exit modes that are applied after
convergence of the solver:
FRC-1.12.1
1)
Discard and continue. (does not save
the solution)
FRC-1.12.2
2)
Save and continue (saves solution to
the initial guess values)
FRC-1.12.3
3)
FRC-1.12.4
The GUI interface shall allow the user to apply
corrections computed by the optimizer
Stop the GMAT run.
Interface/Functional Spec
Overview
Solve for condition(s) by varying one or more parameters.
Script Syntax
Optimize SolverName [{[SolveMode = value], [ExitMode = value]}]
Vary command …
script statement …
NonlinearConstraint command …
Minimize command …
EndOptimize
Note: See the Description, Remarks, and Examples for this complex
command. Multiple Vary and Minimize commands are permitted and
script statements can appear anywhere in the Optimize sequence.
Description
The Optimize command in GMAT allows you to solve optimization problems by using a solver
object. Currently, you can choose from one of two available solvers, the fmincon solver object
available to all GMAT users with access to the Matlab optimization toolbox and the VF13AD solver
object plug-in that you must install yourself.
You use the Optimize and EndOptimize commands to define an “Optimization Sequence” to
determine, for example, the maneuver components required to raise orbit apogee to 42164 km
while simultaneously minimizing the DeltaV required to do so. Optimization sequences in GMAT
are general and this is just an example. Let’s define the quantities that you don’t know precisely
but need to determine as the Control Variables. We define the conditions that must be satisfied as
the Constraints and we define the quantity to be minimized (e.g., DeltaV) as the Objective function.
An optimization sequence numerically solves a boundary value problem to determine the value of
the Control Variables required to satisfy the Constraints while simultaneously minimizing the
Objective function. As was the case for the Target/EndTarget command sequence, you define
your control variables by using Vary commands. You define the constraints that must be satisfied
by using the NonlinearConstraint command and you define the objective function to be minimized
by using the Minimize command. The Optimize/EndOptimize sequence is an advanced
command. The examples later in this section give a more detailed explanation.
See Also: Vary, NonlinearConstraint , and Minimize.
Fields
See the User Interface Spec spreadsheet for reference information for fields.
Team-internal Notes
1
GUI
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 Optimize command allows you to use an optimization process to solve problems. To solve a
given problem, you need to create a so-called Optimize command sequence which we now define.
When you add an Optimize command to the mission sequence, an EndOptimize command is
automatically added as shown below.
Figure 1 Mission Sequence
In the example above, the Optimize command sequence is defined as all of the commands
between the Optimize1 and EndOptimize1 commands, inclusive. Although not shown above, an
Optimize command sequence must contain a Vary command which is used to define the control
variables that can be varied in order to help solve our problem. An Optimize command must also
contain a Minimize command and/or one or more NonlinearConstraint commands. You use a
Minimize command to define a cost function that you wish to minimize and you use the
NonlinearConstrain command to define either an equality or inequality constraint that you want to
be satisfied at the end of the optimization process.
Double click on the Optimize1 command above to open the Optimize command dialog box, shown
below, which allows you to specify your choice of Solver (i.e., your choice of optimizer), Solver
Mode, and Exit Mode. As described in the Remarks section, the Optimize command dialog box
also allows you to apply corrections to your Optimize command sequence.
Figure 2 Optimize command dialog box
Remarks
Content of an Optimize/EndOptimize sequence
An Optimize/EndOptimize sequence must contain at least one Vary command and at least one of
the following commands: NonlinearConstraint and Minimize. See the Vary,
NonlinearConstraint, and Minimize command sections for details on the syntax for those
commands. The First Vary command must occur before the first NonlinearConstraint or
Minimize command. Each Optimize 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 Optimize configuration
fields such as SolveMode and ExitMode.
Relation to Target/EndTarget Command Sequence
There are some functional similarities between the Target/EndTarget and Optimize/EndOptimize
command sequences. In both cases, we define Control Variables and Constraints. For both
Target and Optimization sequences, we use the Vary command to define the Control Variables.
For the Target sequence, we use the Achieve command to define the constraints whereas, for an
Optimization sequence, we use the NonlinearConstraint command. The big difference between
the Target and Optimization sequences is that the Optimization sequence allows for the
minimization of an Objective function through the use of the Minimize command.
Command Interactions
Vary command
Every Optimization sequence must contain at least one
Vary command. Vary commands are used to define the
control variables associated with an Optimization
sequence.
NonlinearConstraint command
NonlinearConstraint commands are used to define the
constraints associated with an Optimization sequence.
Note that multiple NonlinearConstraint commands are
allowed within an Optimization sequence.
Minimize command
A Minimize command is used within an Optimization
sequence to define the Objective function that will be
minimized. Note that an optimization sequence is allowed
to contain, at most, one Minimize command. (An
Optimization sequence is not required to contain a
Minimize command)
Examples
Use an Optimize sequence with the fmincon solver object to find the point, (x, y), on the unit circle
with the smallest y value. Note that the use of the fmincon solver assumes you have access to the
Matlab optimization toolbox.
Create FminconOptimizer SQP1;
SQP1.MaximumIterations = 50;
Create Variable x y Circle
BeginMissionSequence;
Optimize SQP1;
Vary SQP1(x = 1);
Vary SQP1(y = 1);
Circle = x*x + y*y
NonlinearConstraint SQP1(Circle = 1);
Minimize SQP1(y);
EndOptimize;
Similar to the example given in the Target command Help, use an Optimize sequence to raise orbit
apogee. In the Target command example, we had one control variable, the velocity component of
an ImpulsiveBurn object, and the single constraint that the position vector magnitude at orbit
apogee equals 42164. For this example, we keep this control variable and constraint but we now
add a second control variable, the true anomaly of where the burn occurs. In addition, we ask the
optimizer to minimize the Delta-V cost of the burn. As expected, the best (DV minimizing) orbit
location to perform an apogee raising burn is near perigee (i.e., nearTA = 0). In this example,
since the force model in use in not perfectly two body Keplerian, the optimal TA value obtained is
close to but not exactly 0. Note that the use of the VF13AD solver object in this example assumes
that you have installed this optional plug-in.
Create Spacecraft aSat;
Create Propagator aPropagator;
Create ImpulsiveBurn aBurn;
Create VF13ad VF13ad1;
VF13ad1.Tolerance = 1e-008;
Create OrbitView EarthView
EarthView.Add = {Earth, aSat}
EarthView.ViewScaleFactor = 5
Create Variable ApogeeRadius DVCost;
BeginMissionSequence;
Optimize VF13ad1
Vary VF13ad1(aSat.TA = 100, {MaxStep = 10});
Vary VF13ad1(aBurn.Element1 = 1, {MaxStep = 1});
Maneuver aBurn(aSat);
Propagate aPropagator(aSat) {aSat.Apoapsis};
GMAT ApogeeRadius = aSat.RMAG;
NonlinearConstraint VF13ad1(ApogeeRadius=42164);
GMAT DVCost = aBurn.Element1;
Minimize VF13ad1(DVCost);
EndOptimize;
Test Procedures
Assumptions
None.
Existing Tests
There are 15 files of the form *.tc.
Test Name
Optimize_fmincon_Exit
Mode_DiscardAndConti
nue
Optimize_fmincon_Exit
Mode_SaveAndContinu
e
Optimize_fmincon_Exit
Mode_Stop
Optimize_fmincon_Solv
eMode_Defaultscript
Optimize_fmincon_Solv
eMode_RunInitialGuess
Optimize_fmincon_Solv
eMode_Solve
Optimize_vf13ad_ExitM
ode_DiscardAndContinu
e
Description
Optimize_vf13ad_ExitM
ode_SaveAndContinue
Optimize_vf13ad_ExitM
ode_Stop
Optimize_vf13ad_Solve
Mode_Defaultscript
Optimize_vf13ad_Solve
Mode_RunInitialGuess
Optimize_vf13ad_Solve
Mode_Solve
OptimizersInControlFlow
completed_steps_1_thru
_10_of_FRC_1_using_V
F13ad1_Optimizer
completed_steps_1_thru
_10_of_FRC_1_using_f
mincon_Optimizer
Recommended Additional Tests
Unique Validation
Test Name
Summary
Optimize_Validation_vd13ad_Two_Minimi GMT-3216, Verify that case where two minimize
ze_commands
commands are issued is caught.
Optimize_Validation_fmincon_Two_Minim GMT-3216, Verify that case where two minimize
ize_commands
commands are issued is caught.
Optimize_Validation_fmincon_Disallowed
_Sequences
GMT-3216
Optimize_Validation_v13ad_Disallowed_
Sequences
GMT-3216
Optimize_Validation_fmincon_No_Vary_
Command
GMT-3216, At run time, you get error: Solver
subsystem exception: Optimizer cannot initialize: No
variables are set.
Message does not say, “At least one Vary command
is required within an Optimization sequence”
Optimize_Validation_vf13ad_No_Vary_C
ommand
GMT-3216, At run time, you get error: Solver
subsystem exception: Optimizer cannot initialize: No
variables are set.
Message does not say, “At least one Vary command
is required within an Optimization sequence”
Optimize_fmincon_CostFunction_and_Conve GMT-3114
rgedStatus_Display
Optimize_vf13ad_CostFunction_and_Conver
gedStatus_Display
GMT-3114
Optimize_fmincon_Max_Iterations_Display
GMT-3130
Optimize_vf13ad_Max_Iterations_Display
GMT-3130
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
2
Some tests added for Target Command sequence that relate to Optimize command.
a Add tests for GMT-3127, Interpreter does not catch case where Minimize command
is embedded in a Target sequence.
b Add tests for GMT-3130, Confusing message when solver employs maximum
number of iterations if it is a P1 bug.
Three tests added for GMT-3130
'Optimize_vf13ad_Max_Iterations_Display'
'Target_DC_Max_Iterations_Display'
'Optimize_fmincon_Max_Iterations_Display'