Optimizer Object

The Optimizer object provides interfaces for defining and optimizing multi-variable user-defined objective functions. This object allows for the configuration of any number of state variables or constraints, and contains support for minimizing or maximizing an objective as well as solving the constraints for a feasible solution without an objective. The Optimizer object can be loaded with any of the supported third party optimization systems. See the Optimization Guide for more information.

Available In Editions:

Timing Precision Mode

This page describes functionality in millisecond timing precision mode. Millisecond timing precision mode is deprecated and will be removed in a future release. We recommend that you migrate your Mission Plans to nanosecond timing precision mode.

Name	Description	Attributes
Constraints	The constraints in the optimization process.	Type: Array of OptimizationConstraint Access: Read-Only
DeclaredName	The name of the object as declared.	Type: String Access: Read-Only
EngineOutput	StringArray containing all lines written to standard output from the third party optimization library. Note: NLopt does not generate output.	Type: StringArray Access: Read-Only
FeasibilityTolerance	The application of this property depends on which third party optimization engine is loaded. If Ipopt is loaded, this value is used to set the "constr_viol_tol option". If SNOPT is loaded, this value is used to set the "Major feasibility tolerance" and the "Minor feasibility tolerance". If NLopt is loaded, this value is used to set each of the individual constraint tolerances.	Type: Variable Access: Read/Write
FiniteDifferenceMethod	The method used to obtain finite difference derivatives.	Type: Variable Access: Read/Write
Gradient	The Gradient of the objective function. This is the partial derivative of the objective with respect to the state variables. At the beginning of the optimization process, FreeFlyer fills this array with a constant (-999) so that any derivatives the user provides using this array can be automatically detected. All derivatives that the user does not provide will be calculated numerically. When FreeFlyer calculates the derivatives numerically, the elements of the Gradient are filled in one at a time as they are calculated.	Type: Array Access: Read/Write
GradientSparsity	This array represents the sparsity of the gradient. Utilizing this property is not required to solve an optimization problem. However, specifying the complete sparsity structure of a problem (both for the Jacobian and the gradient) in addition to setting Optimizer.ValidateUserDerivatives = 0 will significantly reduce the processing time needed for the Optimizer's sampling phase. If the sparsity isn't specified by the user, then FreeFlyer will detect it automatically. The detected sparsity structure will be readable from this property after the first 3 nominal evaluations of the Optimizer. Each element of this array property is either -999 (corresponds to an unknown element), a 0 (corresponding to an element that is always zero), or a 1 (corresponding to an element that is not always zero).	Type: Array Access: Read/Write
Jacobian	The Jacobian of the constraints. This is the partial derivative of the constraints with respect to the state variables. At the beginning of the optimization process, FreeFlyer fills this matrix with a constant (-999) so that any derivatives the user provides using this matrix can be automatically detected. All derivatives that the user does not provide will be calculated numerically. When FreeFlyer calculates the derivatives numerically, the columns of the Jacobian are filled in one at a time as they are calculated.	Type: Matrix Access: Read/Write
JacobianSparsity	This matrix represents the sparsity of the Jacobian of the user created constraints. It does not include the Jacobian of constraints associated with TrajectorySegment objects. Utilizing this property is not required to solve an optimization problem. However, specifying the complete sparsity structure of a problem (both for the Jacobian and the gradient) in addition to setting Optimizer.ValidateUserDerivatives = 0 will significantly reduce the processing time needed for the Optimizer's sampling phase. If the sparsity isn't specified by the user, then FreeFlyer will detect it automatically. The detected sparsity structure will be readable from this property after the first 3 nominal evaluations of the Optimizer. Each element of this matrix property is either -999 (corresponds to an unknown element), a 0 (corresponding to an element that is always zero), or a 1 (corresponding to an element that is not always zero).	Type: Matrix Access: Read/Write
LastGeneratedEngineOutput	The most recent line or set of lines (newline delimited) reported from the optimization engine. Note: NLopt does not generate output.	Type: String Access: Read-Only
MaximumInfeasibility	The current maximum violation of both the state variable bounds and the constraint bounds. This property is updated anytime the Minimize/Maximize Optimizer methods are used.	Type: Variable Access: Read-Only
MaximumInfeasibilitySource	Holds the string label corresponding to the state variable or constraint that possesses the highest bound violation (see the Optimizer.MaxInfeasibility propery for more information). Labels for TrajectoryPhase variables/constraints are formatted as follows: ___________________________________________________________ Variables: phaseA_nB_C A : The phase number B : The node number. C : The state, time, or control element. Can be: x, y, z, vx, vy, vz, mass, time, or uD, where D is the control variable number. ___________________________________________________________ Collocation defect constraints: phaseA_cB_C A : The phase number B : The collocation point number. C : The state derivative element. Can be: vx, vy, vz, ax, ay, az, or mdot. ___________________________________________________________ Node spacing constraints: phaseA_nB_spacing A : The phase number. B : The node number. ___________________________________________________________ Control model path constraints: phaseA_nB_cmpc_C A : The phase number. B : The node number. C : A short description of the path constraint. ___________________________________________________________ Time of flight constraint: phaseA_tof A : The phase number. ___________________________________________________________ State boundary constraints: phaseA_sbc_B_C A : The phase number. B : The endpoint of the state boundary constraint. C : A short description of the state boundary constraint. ___________________________________________________________ State path constraints: phaseA_spc_nB_C A : The phase number. B : The node number. C : A short description of the state path constraint. ___________________________________________________________ Interphase link constraints: link_A_pB_C_pD_E A : The link endpoint of the first phase B : The phase number of the first phase. A : The link endpoint of the second phase D : The phase number of the second phase. E : A short description of the interphase constraint. Note: All phase/node/collocation point numbers are equivalent to the corresponding index plus one. In other words, the first node point corresponds to node number 1. Phases are numbered in the order they were added to the optimizer.	Type: String Access: Read-Only
MaximumNominalEvaluationCount	Defines the maximum number of nominal evaluations that will be performed before the optimization process is terminated.	Type: Variable Access: Read/Write
Name	The name displayed for this object in output windows such as views, plots, and reports.	Type: String Access: Read/Write
NominalEvaluationCount	The current number of nominal evaluations that have been completed.	Type: Variable Access: Read-Only
NumberOfConstraints	The number of Constraints in the optimization process.	Type: Variable Access: Read-Only
NumberOfStateVariables	The number of StateVariables in the optimization process.	Type: Variable Access: Read-Only
ObjectId	The unique identifier for the object.	Type: Variable Access: Read-Only
ObjectiveFunctionLabel	Label associated with the objective function being minimized or maximized. This is used only for reporting.	Type: String Access: Read/Write
ObjectiveFunctionScale	The scale used for the objective function. This can be used to normalize the objective function value to be the same order of magnitude of constraints and state variables to preserve better matrix conditioning.	Type: Variable Access: Read/Write
ObjectiveFunctionValue	The last evaluated value of the objective function. This is set from the Optimize method.	Type: Variable Access: Read-Only
ObjectType	The type of the object.	Type: String Access: Read-Only
OptimizationPhase	Reports the phase of the Optimization process, which indicates whether the current iteration is associated with a nominal guess, or in evaluating a derivative.	Type: Variable Access: Read-Only
ProblemName	The name associated with the problem being solved. This is used only for reporting.	Type: String Access: Read/Write
ReturnCode	Holds the return code of the optimizer after the optimization process completes. Note that this code is specific to the optimization library being used.	Type: Variable Access: Read-Only
ReturnString	Holds the return string of the optimizer after the optimization process completes. Note that this code is specific to the optimization library being used.	Type: String Access: Read-Only
ScaledGradient	The scaled Gradient of the objective function. This represents the Gradient after it has been transformed using the scales of the state variables and objective.	Type: Array Access: Read-Only
ScaledJacobian	The scaled Jacobian of the constraints. This represents the Jacobian after it has been transformed using the scales of the state variables and constraints.	Type: Matrix Access: Read-Only
StateVariables	The state variable in the optimization process.	Type: Array of OptimizationStateVariable Access: Read-Only
ThirdPartyLibraryName	The name of the third pary optimization library that is currently loaded. This property will be blank until the optimizer loads an optimization engine.	Type: String Access: Read-Only
TotalEvaluationCount	The current total number of evaluations of the constraints and the objective function.	Type: Variable Access: Read-Only
TrajectoryPhases	The TrajectoryPhases that have been added to the optimizer.	Type: Array of TrajectoryPhase Access: Read-Only
UseJacobianSparsity	Determines whether to process only the nonzero portion of the Jacobian. If this property is set to 0, the Jacobian will be treated as fully dense.	Type: Variable Access: Read/Write
ValidateUserDerivatives	Determines whether initial validation is performed on the values of user-provided derivatives. When set to true, an error is reported if a user-provided derivative is more than 10% different than the finite difference derivative evaluated during the sampling process.	Type: Variable Access: Read/Write

Name	Description
AddConstraint	Creates a new entry in the Optimizer.Constraints array with the specified label.
AddConstraintBlock	Adds a block of Constraints.
AddPhaseEpochLink	Links the phases across the epoch variable. Note: This method adds constraint(s) to the optimization problem to ensure that the phases are continuous.
AddPhaseLink	Links the phases across the position, velocity, mass, and epoch variables. Note: This method adds constraint(s) to the optimization problem to ensure that the phases are continuous.
AddPhaseLinkByIndices	Links the phases across the variables indicated by the passed indices. Note: This method adds constraint(s) to the optimization problem to ensure that the phases are continuous.
AddPhaseLinkDeltaVConstraint	Creates a delta V link constraint between two TrajectoryPhases.
AddPhaseMassLink	Links the phases across the mass variable. Note: This method adds constraint(s) to the optimization problem to ensure that the phases are continuous.
AddPhasePositionLink	Links the phases across the position variables. Note: This method adds constraint(s) to the optimization problem to ensure that the phases are continuous.
AddPhaseVelocityLink	Links the phases across the velocity variables. Note: This method adds constraint(s) to the optimization problem to ensure that the phases are continuous.
AddStateVariable	Creates a new entry in the Optimizer.StateVariables array with the specified label.
AddStateVariableBlock	Creates n new entries in the Optimizer.StateVariables array. Label is used as a prefix to create incremented labels for each entry.
AddTrajectoryPhase	Adds a TrajectoryPhase to the optimization problem. When the Optimizer.LoadEngine method is called, all variables and constraints associated with the added TrajectoryPhases will be automatically added to the optimization problem.
ClearSavedStates	Clears previous saved states for this object.
FeasibleSolutionFound	Returns 1 if the optimizer is has found a feasible solution, otherwise returns 0. This assessment is based on the ConstraintTolerance Optimizer property.
GetBestConstraintValue	Returns the value of the specified constraint corresponding to the best solution found so far. Calling this method before the first Optimizer evaluation is complete will return -999.
GetBestConstraintValues	Returns an array containing the values of the constraints corresponding to the best found solution so far. Calling this method before the first Optimizer evaluation is complete will return an Array of -999.
GetBestObjectiveFunctionValue	Returns objective function value corresponding to the best feasible solution found so far. Calling this method before the first Optimizer evaluation is complete will return -999.
GetBestSolutionMaximumInfeasibility	Returns the maximum scaled infeasibility of the current best solution. Calling this method before the first Optimizer evaluation is complete will return -999.
GetBestStateVariableValue	Returns the value of the specified state variable corresponding to the best solution found so far. Calling this method before the first Optimizer evaluation is complete will return -999.
GetBestStateVariableValues	Returns an array containing the values of the state variables corresponding to the best solution found so far. Calling this method before the first Optimizer evaluation is complete will return an Array of -999.
GetConstraint	Gets a reference to the Constraint associated with the specified label. If no Constraint is associated with that label, an error is reported.
GetConstraintIndex	Returns the index of the Constraint with the specified label, or -1 if the entry is not found.
GetConstraintValue	Returns the current value of the requested constraint.
GetConstraintValues	Returns an array of the most recent values for the constraints that have been evaluated.
GetFromFile	Load the object state from the specified FreeFlyer object file.
GetFromString	Load the object state from the specified string.
GetStateVariable	Gets a reference to the StateVariable associated with the specified label. If no StateVariable is associated with that label, an error is reported.
GetStateVariableIndex	Returns the index of the StateVariable with the specified label, or -1 if the entry is not found.
GetStateVariableValue	Returns the current value of the requested state variable. The current value is obtained from the third party optimization engine, and is updated upon every call to Minimize/Maximize.
GetStateVariableValues	Returns an array of the most recent values for the state variables that have been evaluated.
HasNotConverged	Returns 0 if the optimization engine has indicated that it has converged, otherwise returns 1. If the optimizer exits with a non-converged return code, an error occurs.
IsFeasible	Returns 1 if the current evaluation is feasible, otherwise returns 0. This assessment is based on the ConstraintTolerance Optimizer property.
IsRunning	Returns 1 if the optimizer is currently running, otherwise returns 0.
LoadEngine	Loads and initializes the third party engine to be used in the optimization process. At this time, the engine is configured to process the specified state variables and constraints.
Maximize	Process the evaluated constraints and the specified objective function value to be maximized.
Minimize	Process the evaluated constraints and the specified objective function value to be minimized.
PutToFile	Convert the object state to FreeFlyer object xml and write to a file.
PutToString	Convert the object state to FreeFlyer object xml and return as a string.
ReferenceEquals	Returns 1 if the argument refers to the calling object and 0 otherwise.
RemoveAllPhaseLinkConstraints	Removes all link constraints between TrajectoryPhases.
RemoveAllTrajectoryPhases	Removes all TrajectoryPhase's from the Optimizer.TrajectoryPhases list. Also removes all inter-phase links from the Optimzier.
RemoveTrajectoryPhase	Removes the passed TrajectoryPhase from the Optimizer.TrajectoryPhases list. This method will produce an error if the passed TrajectoryPhase is not in the Optimizer.TrajectoryPhases list. After removing the TrajectoryPhase, all inter-phase constraints having no remaining link points attached to the Optimizer will be removed.
Reset	Resets the optimization process.
Restore	Restore an object's state from a previously saved state.
RestoreObjectsInProcess	Restores all objects that have been saved using the Optimizer.SaveObjectToProcess() method.
Save	Save the object's state so that it can be restored later.
SaveObjectToProcess	Saves the initial state of the object. The object will be restored to this initial state whenever the Optimizer.RestoreObjectsInProcess() method is called.
SetConstraintValue	Sets the value of the specified constraint.
SetConstraintValues	Sets the constraint values from an array. The constraintValues array must be of the same length as the optimizer's current Constraints array.
SetGradientSparsityValue	Sets a value in the Optimizer.GradientSparsity array.
SetGradientValue	Sets the value of the element of the Gradient that is associated with the specified StateVariable.
SetInitialGuess	Sets the initial guess to be used by the optimizer. The initialGuessValues array must be of the same length as the optimizer's current StateVariables array.
SetJacobianSparsityValue	Sets a value in the Optimizer.JacobianSparsity matrix.
SetJacobianValue	Sets the value of a Jacobian element.
SolveConstraints	Process the evaluated constraints and solve them without respect to an objective function.
UpdateStateVariables	Retrieves the next iteration of state variable values from the optimization process and stores them in the Optimizer object so that they can be subsequently used for evaluating the constraints and objective function. A call to this method should be placed at the top of the optimizer evaluation loop.

Optimizer Object

Description

Available In Editions:

Timing Precision Mode