Vary
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
Vary_Validation_MinimizeInIf
GMT-3056
GMT-3056
Vary_Validation_OptimizerVaryInFor
GMT-3056
Vary_Validation_OptimizerVaryInWhile
GMT-3056
Vary_DC_PiC_Additive_and_Multiplicative_ScaleFactor_RealNumber
GMT-2895
Vary_optimizer_fmincon_Additive_and_Multiplicative_ScaleFactor_RealNumber
GMT-2895
Vary_optimizer_VF13ad1_Additive_and_Multiplicative_ScaleFactor_RealNumber
GMT-2895
Vary_Validation_WithinTarget_MaxStep_Negative
GMT-350
Vary_Validation_WithinTarget_Lower_GT_Upper
GMT-350
Appendix A - Miscellaneous Data
STK GUI Screen Snaps:
NOTES
Explore
Known bugs/issues committed in JIRA against this feature:
JIRA ID
Summary
Comment
GMT-3047
Can't Vary Finite Burn Direction in
Targeter
Added documentation to the
"Remarks" section of the Vary
command feature spec. Bug closed.
GMT-2895
Additive and multiplicative scale factor
fields active for differential corrector
Added 3 new tests to test how additive
and multiplicative scale factors are
used. According to the output
message window, all three solvers
(DC, fmincon, VF13ad1) use both the
additive and multiplicative fields.
Bug closed. Re-assigned to Darrel for
further verification. Issue closed
10/31/12.
GMT-2522
AdditiveScaleFactor,
MultiplicativeScaleFactor descriptions
wrong
Updated the Vary Command
feature/field spec as required. To
complete other items (not related to
Vary command feature/field spec), the
bug status was changed, per GMAT
10/4/12 status meeting, to P3 and
assigned to Darrel. No further action
from DSC required.
GMT-1949
Vary command accepts repeated
parameters
A note was added to the Remarks
section. Currently assigned to Steve
H. to determine if anything else needs
to be done. (Still Open, assigned to
SPH, as of 11/21/12)
GMT-1426
Vary command validation issue
Steve H. shows an example where the
Vary command does not handle userdefined coordinate systems Per Steve
H, sent to CCB for re-triage on 10/1.
CCB classifies as P1 and Steve H.
assigned to fix error message.
Steven Hughes added a comment 06/Nov/12 6:03 PM
CCB: P1 R2013a, SPH can't fix the
message so assigning back to DJC.
Still open as of 11/21/12.
GMT-414
Vary Command Allows Selecting Read
Only Parameters using Parameter
Need to make sure that no read-only
variables show up in the VARY
ParameterSelectDialog. Per Steve H
guidance, have asked Joel for list of which
variables are settable vs. gettable.
(10/12/12).
Still open as of 11/21/12. Have asked for
status of 10/12/12 email.
GMT-2586
User allowed to delete references for
Vary panel
Issue listed as “resolved.” Shawn is
assigned to verify. No further action
from DSC required.
GMT-350
Vary window does not perform field
validation
Steve H. noted that it is Ok to catch
these errors at run-time since some of
the Vary command inputs can be
variables as opposed to Real numbers.
(Added regression tests which passed)
The case where Lower > upper was
caught only at run time:
Solver subsystem exception: Minimum allowed
variable value (received 2) must be less than
maximum (received 1)
The case where the max step was
negative was only caught at run-time:
Solver subsystem exception: Largest allowed step
must be positive! (received -0.2)
The case where the perturbation was
negative was not caught at all. But this
is OK since perturbation is allowed to
be negative. Vary
DefaultDC(DefaultIB.Element1 = 0.5, {Perturbation = 0.0001, Lower = 1, Upper = 2, MaxStep = 0.2,
AdditiveScaleFactor = 0.0, MultiplicativeScaleFactor =
1.0});
The run-time error received when
MultiplicativeScaleFactor is negative is
weird (Steve H thought upper and
lower bounds should be scaled as well.
Steve H thought it was OK for the
Multiplicative scale factor to be
negative. Needs more investigation):
CMD is Vary
DefaultDC(DefaultIB.Element1 = 0.5,
{Perturbation = -0.0001, Lower = 1,
Upper = 2, MaxStep = 0.2,
AdditiveScaleFactor = 0.0,
MultiplicativeScaleFactor = -1.0});
Error is
Solver subsystem exception: Minimum allowed
variable value (received -1) must be less than
maximum (received -2). See Appendix for
explanation of behavior.
Bug still open as of 11/21/12. Added
regression test for negative
multiplicative scale factor case. Test
will pass once error message updated.
GMT-2976
Syntax highlighting is incomplete. See
Appendix for more complete
description.
As this is not a Vary problem, Steve
said not to worry about this bug. Joel
will handle.
GMT-3056
Vary command in control flow is not
allowed but no exception thrown
Non-branch solver commands (Vary,
Achieve, NonlinearConstraint,
Minimize) can not be nested inside
control flow branch commands (If, For,
While). Regression tests added. Bug
closed.
GMT-3050
Users can script Solver Control
Sequences with the wrong solver types
Added regression tests. Closed bug.
Note that GMT-2638 is the Achieve QA task (not a bug).
Failing Tests
Run Identification: [Gmat-buildtest] Test results: 2012-09-13 (Win7-64/GMAT-32/M2010a/VS)
These tests have script errors that caused a failure:
Vary_optimizer_fmincon_InitialGuess_ForLoopVariable (script) Output file
C:\Users\Public\Documents\JAZZ\trunk\test\script\gmat\output\Vary_optimizer_fmincon_InitialGuess_Fo
rLoopVariable.report does not exist
Comments/Actions Taken:
● Ran locally, and got the following odd error. Sent email to Steve H/Joel/Darrel asking for
help.
SQP1 Iteration 1; External Run
Variables: TOI.Element1 = 0.3
Interface Exception Thrown: ".m", Error using ddepoke
The first argument 'channel' is not valid.
*** Mission run failed.
===> Total Run Time: 76.149000 seconds
●
Submitted bug, GMT-3116, Fmincon does not work within a For loop. Status: Still open as
of 11/21/12, assigned to LJ.
These tests run to completion but fail:
Vary_optimizer_fmincon__AdditiveScaleFactor_Variable (script) []
Vary_DC_PiC_AdditiveScaleFactor_RealNumber (script) []
Vary_DC_PiC_MultiplicativeScaleFactor_ArrayElement (script) []
Vary_DC_PiC_AdditiveScaleFactor_ArrayElement (script) []
Vary_DC_PiC_MultiplicativeScaleFactor_RealNumber (script) []
Vary_DC_PiC_MultiplicativeScaleFactor_Variable (script) []
Vary_optimizer_VF13ad1_AdditiveScaleFactor_ArrayElement (script) []
Vary_optimizer_VF13ad1_AdditiveScaleFactor_RealNumber (script) []
Vary_optimizer_VF13ad1_AdditiveScaleFactor_Variable (script) []
Vary_optimizer_VF13ad1_MultiplicativeScaleFactor_ArrayElement (script) []
Vary_DC_PiC_AdditiveScaleFactor_Variable (script) []
Vary_optimizer_VF13ad1_MultiplicativeScaleFactor_Variable (script) []
Vary_optimizer_fmincon_AdditiveScaleFactor_ArrayElement (script) []
Vary_optimizer_fmincon_AdditiveScaleFactor_RealNumber (script) []
Vary_optimizer_fmincon_MultiplicativeScaleFactor_ArrayElement (script) []
Vary_optimizer_fmincon_MultiplicativeScaleFactor_RealNumber (script) []
Vary_optimizer_VF13ad1_MultiplicativeScaleFactor_RealNumber (script) []
Vary_optimizer_fmincon_MultiplicativeScaleFactor_Variable (script) []
Comments/Actions Taken:
● All the tests above pass if run locally. Sent email to Joel/Steve H (9/20/12) requesting
debug help for the nightly regression system.
Vary_Validation_VF13ad1_RepeatedSetting (script) [no warn or err]
Vary_Validation_fmincon_RepeatedSetting (script) [ptrn 1 failed]
Vary_Validation_RepeatedSetting (script) [no warn or err]
Comments/Actions Taken:
● It is no surprise that the tests above fail. GMAT does not give any warning if you repeat
setting of a sub-command. See GMT-1949. Status: Still open as of 11/21/12, assigned to
SPH, asking if anything else needs to be done. Sent email to SPH.
Other Findings
1
2
Within a Target sequence using a DC, GMAT appears to work fine if the initial guess does
not fall within the Lower and Upper bounds.
Negative perturbation step sizes (set as part of the Vary command) are OK. Question to
Darrel: Do you think negative pert sizes are OK? Response:
Yes. That is similar in effect to doing backwards differencing, but it gives finer
grained control over what increases and what decreases (the ones with negative perts) when
building the Jacobian.
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
FRC-2.1.0
Requirement
The system shall have a command named Vary that allows the user to define
control variables in the following solver sequences:
FRC-2.1.1
1)
Target
FRC-2.1.2
2)
Optimize
FRC-2.2.0
The Vary command shall support the following settings when using the
differential corrector:
FRC-2.2.1
1)
Initial Value
FRC-2.2.2
2)
Perturbation for finite differencing
FRC-2.2.3
3)
Lower Bound on control variable
FRC-2.2.4
4)
Upper bound on control variable
FRC-2.2.5
5)
Maximum step per iteration
FRC-2.2.6
6)
Additive scale factor
FRC-2.2.7
7)
Multiplicative scale factor
FRC-2.3.0
The Vary command shall support the following settings when using the
fmincon optimizer:
FRC-2.3.1
1)
Initial Value
FRC-2.3.2
2)
Lower Bound on control variable
FRC-2.3.3
3)
Upper bound on control variable
FRC-2.3.4
4)
Additive scale factor
FRC-2.3.5
5)
Multiplicative scale factor
FRC-2.4.0
The Vary command shall support the following settings when using the vf13ad
optimizer:
FRC-2.4.1
1)
Initial Value
FRC-2.4.2
2)
Perturbation for finite differencing
FRC-2.4.3
3)
Maximum step per iteration
FRC-2.4.4
4)
Additive scale factor
FRC-2.4.5
5)
Multiplicative scale factor
FRC-2.5.0
The system shall support the following control variables in the Vary command:
FRC-2.5.1
1)
Any scalar, read/write parameter defined in
FRC-2.5.2
2)
Any user-defined variable
FRC-2.5.3
3)
Any user-defined array element
FRC-2.5.4
4)
Real number
FRR-38
FRC-2.6
DEFERRED: The vary command shall provide a warning message if the user
sets fields on the vary command that are not supported by the selected
solver. (Some explanation is in order here: the vary command is used by all
solvers to define the control variables. However, third party solvers do not
support all options in the Vary command. This requirement ensures that if a
user tries to configure the Vary command in a way not supported by the
chosen solver, the system will let them know.)
Interface/Functional Spec
Overview
Specifies the variables used by a solver to solve for user specified condition(s).
Script Syntax
Vary SolverName(<UserSelectedControl>=InitialGuess,
[{[Perturbation=Arg1], [MaxStep=Arg2],
[Lower=Arg3], [Upper=Arg4],
[AdditiveScalefactor=Arg5], [MultiplicativeScalefactor=Arg6]}])
Note: See the Description below and also the Target or Optimize
command help for this complex command.
Description
The Vary command is used in conjunction with either the Target or the Optimize command. The
Vary command defines the control variable used by the targeter or optimizer. The Target or
Optimize sequence then varies these control variables until certain desired conditions are met.
Every Target or Optimize sequence must contain at least one Vary command.
See Also: DifferentialCorrector, FminconOptimizer, VF13ad, Target, Optimize
Fields
See the User Interface Spec spreadsheet for reference information for fields.
GUI
The Vary command, only valid within either a Target or an Optimize sequence, is used to define
the control variables which will be used to solve a problem. The Vary command dialog box is
shown below.
The Vary command dialog box allows you to specify
1 Choice of Solver (a differential corrector if using a Target sequence or an optimizer if using
an Optimize sequence).
2 Control Variable object. To define the control variable used in the Vary command, click the
Edit button to bring up the ParameterSelectDialog as shown below. Use the arrow to
select the desired object and then click OK.
3
4
5
6
7
8
9
Initial value for the control variable object.
Perturbation Step size used as part of the finite differencing algorithm. As noted in the
Remarks section, this field is only used if the solver chosen is a differential corrector or a
VF13AD optimizer.
Lower allowed limit for the converged control variable object. As noted in the Remarks
section, this field is only used if the solver chosen is a differential corrector or a fmincon
optimizer.
Upper allowed limit for the converged control variable object. As noted in the Remarks
section, this field is only used if the solver chosen is a differential corrector or a fmincon
optimizer.
Maximum Step size, per iteration, for the control variable object. As noted in the Remarks
section, this field is only used if the solver chosen is a differential corrector or a VF13AD
optimizer.
Additive scale factor used to scale the control variable object.
Multiplicative scale factor used to scale the control variable object.
Remarks
Vary Command Options
The Vary command is designed to work with all three of the GMAT Targeters and Optimizers
(Differential Corrector, fmincon, and VF13AD). The solvers, which are developed by different
parties, all work slightly differently and thus have different needs. The table below shows which
command options are available for a given solver.
Differential Corrector
fmincon
VF13AD
SolverName
x
x
x
Variable
x
x
x
InitialGuess
x
x
x
AdditiveScaleFactor
x
x
x
MultiplicativeScaleFactor
x
x
x
Lower
x
x
Upper
x
x
Perturbation
x
x
MaxStep
x
x
The Vary syntax allows you to specify the value of an option even if a particular solver would not
use the information.
Vary command accepts repeated parameters
As shown in the example below, the Vary command accepts repeated parameters.
Vary DefaultDC(ImpulsiveBurn1.Element1 = 2, ...
{Perturbation = 1e99, Perturbation = .001});
The accepted best practice is not to repeat parameters in any given command. However, for the
Vary command, if you accidentally sets the same parameter multiple times, the last setting takes
precedence. Thus, in the example above, the perturbation step size is set to 0.001.
Use of Thruster parameters in a Vary command
If you wish to use thruster parameters, such as thrust direction, in a Vary command, then you must
reference the cloned (child) object directly. In the example below, we first show syntax, using the
parent object that does not work. We then show the correct syntax using the cloned (child) object.
%Referencing the parent object, thruster1, does not work.
Vary DC1(thruster1.ThrustDirection1 = 0.4);
Vary DC1(thruster1.ThrustDirection2 = 0.5);
%Referencing the cloned (child) object, Sc.thruster1, does work.
Vary DC1(Sc.thruster1.ThrustDirection1 = 0.4);
Vary DC1(Sc.thruster1.ThrustDirection2 = 0.5);
Command Interactions
Target command
A Vary command only occurs within a Target or Optimize
sequence.
Optimize command
A Vary command only occurs within a Target or Optimize
sequence.
Achieve command
The Achieve command, used as part of a Target
sequence, specifies the desired result or goal (obtained
by using the Vary command to vary the control variables).
NonlinearConstraint command
The NonlinearConstraint command, used as part of an
Optimize sequence, specifies the desired result or goal
(obtained by using the Vary command to vary the control
variables).
Minimize command
The Minimize command, used as part of an Optimize
sequence, specifies the desired quantity to be minimized
(obtained by using the Vary command to vary the control
variables).
Examples
See the Target and Optimize command help for examples showing the use of the Vary command.
Test Procedures
Assumptions
None
Existing Tests
There are 194 files of the form *.tc.
Test Name
Description
Vary_DC*.tc
There are 22 files of this type.
Vary_optimizer_fmincon*.tc
There are 19 files of this type.
Vary_optimizer_VF13ad1
*.tc
There are 15 files of this type.
Vary_optimizer_VF13ad_InitialGu
ess_ForLoopVariable.tc
There is one file of this type.
Vary_Validation*.tc
Validation type tests. There are 137 tests of this
type.
According to the table above, there are
22 + 19 + 15 + 1 + 137 = 194
files accounted for which agrees with the known number of test cases.
Recommended Additional Tests
1
2
3
4
Added 16 tests to verify GMT-3056 and to close issue. These tests include the following:
a Vary (in a Target sequence) nested in (For/If/While) command
b Vary (in an Optimize sequence) nested in (For/If/While) command
c Achieve nested in (For/If/While) command
d NonlinearConstraint nested in (For/If/While) command.
e Minimize nested in (For/If/While) command
Added 3 tests for GMT-2895. Issue closed.
Added 3 tests for GMT-350. Issue closed.
Added 2 tests for GMT-3050. Issue closed.
Unique Validation
Test Name
Summary
Vary_Validation_AchieveInIf
Generates Error message, ‘...is a Solver command,
and cannot be nested inside...’ Based on Darrel’s
system test of similar name. GMT-3056
Vary_Validation_OptimizerVaryInIf
Generates Error message, ‘...is a Solver command,
and cannot be nested inside...’ (Based on Darrel’s
system test of similar name. Had to add If sequence to
Darrel’s script) GMT-3056
Vary_Validation_SolverMismatch
Generated Error message, ‘,,,in the Vary command
does not match the Solver...’ Based on Darrel’s
system test of similar name. Vary command
(specifying a DC type of solver) used in an Optimize
sequence. GMT-3050.
Vary_Validation_SolverMismatch_2
Vary command (specifying an Optimizer type of solver)
used in a Target sequence. GMT-3050.
Vary_Validation_TargetInFor
No error message generated. Entire Target/EndTarget
sequence nested inside a For loop. Based on Darrel’s
system test of similar name. GMT-3056
Vary_Validation_VaryInFor
Generates Error message, ‘...is a Solver command,
and cannot be nested inside...’ Vary command is
inside a Target sequence. (Based on Darrel’s system
test of similar name.) GMT-3056
Vary_Validation_VaryInIf
Generates Error message, ‘...is a Solver command,
and cannot be nested inside...’ Vary command is
inside a Target sequence. (Based on Darrel’s system
test of similar name.) GMT-3056
Vary_Validation_VaryInIfInTargetInFor
Generates Error message, ‘...is a Solver command,
and cannot be nested inside...’ Based on Darrel’s
system test of similar name. GMT-3056
Vary_Validation_VaryInWhile
Generates Error message, ‘...is a Solver command,
and cannot be nested inside...’ Vary command is
inside a Target sequence. (Based on Darrel’s system
test of similar name.) GMT-3056
Vary_Validation_AchieveInWhile
GMT-3056
Vary_Validation_AchieveInFor
GMT-3056
Vary_Validation_NonlinearConstraintIn
If
GMT-3056
Vary_Validation_NonlinearConstraintIn
For
GMT-3056
Vary_Validation_NonlinearConstraintIn
While
GMT-3056
Vary_Validation_MinimizeInFor
GMT-3056
Vary_Validation_MinimizeInIf
GMT-3056
Vary_Validation_MinimizeInWhile
GMT-3056
Vary_Validation_OptimizerVaryInFor
GMT-3056
Vary_Validation_OptimizerVaryInWhile
GMT-3056
Vary_DC_PiC_Additive_and_Multiplica
tive_ScaleFactor_RealNumber
GMT-2895
Vary_optimizer_fmincon_Additive_and GMT-2895
_Multiplicative_ScaleFactor_RealNumb
er
Vary_optimizer_VF13ad1_Additive_an GMT-2895
d_Multiplicative_ScaleFactor_RealNum
ber
Vary_Validation_WithinTarget_MaxSte
p_Negative
GMT-350
Vary_Validation_WithinTarget_Lower_
GT_Upper
GMT-350
Vary_Validation_Negative_Multiplicativ
eScaleFactor
GMT-350
Vary_Validation_Different_SC_Coordin
GMT-1426. Verify get error message if spacecraft
ateSystems
coordinate system (e.g., DefaultSC.CoordinateSystem
= EarthMJ2000Eq) is different from coordinate system
used in Vary command (e.g., Vary
DefaultDC(DefaultSC.LunarMOP.VMAG = 2.445);)
Vary_Validation_Use_Parent_Object
Verify that appropriate error message is received when
one uses the parent object (e.g.,
thruster1.ThrustDirection2)in the Vary
command.
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.
STK GUI Screen Snaps:
NOTES
1
GMT-2976 Details
This is an impression-of-quality issue.
The syntax highlighting in the script editor is incomplete.
This needs a more thorough inspection, but here's some things I see from looking at the Hohmann
sample:
● DifferentialCorrector is blue, but Spacecraft, Propagator, ForceModel, etc. aren't
● MaxStep is blue, but no other fields of Propagator are
● true/false are blue, but yes/no and on/off aren't
● Comments aren't highlighted
● keywords in comments are highlighted
● Vary command Lower option is highlighted, but Perturbation isn't
● transpose operator is highlighted like a mismatched string quote
2 Graphic below for possible later use:
For Tech writer: When migrating the field spec data to the Users Guide, ...
1
Steve H made the following change.
Ok. Thanks. Some tests will fail but easy to fix
On Oct 4, 2012, at 4:56 PM, "Hughes, Steven P. (GSFC-5950)" <steven.p.hughes@nasa.gov>
wrote:
I fixed it and it should be in tomorrow’s build. Thanks for pointing out. Engineers are allowed to
make these types of changes.
From: Cooley, D S. (GSFC-5950)
Sent: Thursday, October 04, 2012 4:45 PM
To: Hughes, Steven P. (GSFC-5950)
Cc: Cooley, D S. (GSFC-5950); Darrel Conway
Subject: P3 bug?
Steve,
I assume that both VF13ad and fmincon are optimizers.
When fmincon is used, one receives an output such as
optimizer scaled value: 22
But, when VF13ad is used, one receives an output such as
targeter scaled value: 22
I assume that the VF13ad message should use the word ‘optimizer’ as well. Do you agree? If so, should I document
this somewhere? Perhaps, it can be a P3 bug.
steve
3
4
For bug 3047, wonder if we get same behaviour inside an Optimize sequence. May want
to check time permitting.
GMT-350
Suppose have Vary command shown below
Vary VF13ad1(DeltaV.Element1 = 6,{Perturbation = 1, Lower = -1000, Upper = 2000,
AdditiveScaleFactor = 4,MultiplicativeScaleFactor = -3});
Looks like GMAT has a minimum allowed control variable value must be less than
maximum type of test that is performed. It also appears that this test is done using the
scaled values.
>>MINIMUM = (-1000 +4) * (-3)
ans =
2988
>> MAXIMUM = (2000 +4) * (-3)
ans =
-6012
Compare this to message received:
Solver subsystem exception: Minimum allowed variable value (received 2988) must be less
than maximum (received -6012)
So, this test fails because of negative multiplicative scale factor.
5
6
In the Mission tree, append either a Target command or an Optimize command sequence.
Then, insert a Vary command into the newly created Target or Optimize sequence.
Double click the newly created Vary command to bring up the following window.
If you mistype Thruster1 (e.g., small case for T), you get an unhelpful error message:
Command Exception: **** ERROR **** Error scripting the variable in the Vary command: Coordinate systems and Central
Bodies are not supported on the left hand side at this time in line:
Vary DC1(DefaultSC.thruster1.ThrustDirection1 = 1, {Perturbation = 0.001, Lower = -9.999999e300, Upper = 9.999999e300, MaxStep =
9.999999e300, AdditiveScaleFactor = 0.0, MultiplicativeScaleFactor = 1.0});
*** Mission run failed.