3.11. Hint Reference

GTOpt hints specify types of variables and additional properties of objectives and constraints in an optimization problem.

• You can specify hints in your problem class definition when adding variables, objectives, and constraints — see the hints dictionary argument to add_variable(), add_objective(), add_constraint().
• You can set hints in an instance of your problem class — see set_variable_hints(), set_objective_hints(), and set_constraint_hints().

This section lists available hints, corresponding keys recognized in hints, and their valid values.

Variable Hints

• key: "@GT/FixedValue" (added in 6.35), value: any floating point number for a continuous variable, one of the variable’s levels for other types
• key: "@GT/Resolution" (added in 6.29), value: positive floating point number
• key: "@GT/VariableType", value: "Continuous" (default), "Integer", "Discrete", "Stepped", or "Categorical"

Changed in version 6.1: solving non-linear mixed integer problems no longer requires defining some objective or constraint as expensive (using the @GTOpt/EvaluationCostType hint); GTOpt uses surrogate-based optimization (SBO) in such problems by default.

Changed in version 6.14: renamed the key to "@GT/VariableType" since it is now also used by a similar hint in GTDoE.

Changed in version 6.15: added the discrete variable type.

Changed in version 6.29: added the stepped variable type.

Changed in version 6.29: added the variable resolution hint, see @GT/Resolution for details.

Changed in version 6.33: added support for the categorical variable type.

Changed in version 6.35: added the @GT/FixedValue hint.

Objective Hints

• key: "@GTOpt/EvaluationCostType", value: "Cheap" (default) or "Expensive"
• key: "@GT/EvaluationLimit" (added in 6.32, updated in 6.39), value: integer in range \([1, 65535]\), 0 (deferred evaluation), -1, or "Auto" (no specific limit, default); -1 and "Auto" are the same
• key: "@GTOpt/ExpensiveEvaluations" — deprecated since 6.32, use "@GT/EvaluationLimit" instead
• key: "@GTOpt/LinearityType", value: "Generic" (default), "Linear", or "Quadratic"
• key: "@GT/ObjectiveType" (added in 6.35), value: "Minimize", "Maximize", "Evaluate", or "Auto" (default); "Auto" defaults to "Minimize"

Changed in version 1.10.2: GTOpt now allows multiple expensive objectives and/or constraints in the given problem, thus supporting the multi-objective surrogate based optimization. Prior to 1.10.2, SBO was supported only in problems with a single objective or functional constraint (single-objective box-constrained problems and constraint satisfaction problems with one constraint).

Changed in version 6.6: the @GTOpt/LinearityType hint is no longer ignored in robust optimization problems. However, GTOpt now assumes that objectives hinted as linear or quadratic do not depend on any stochastic variable. This can lead to unexpected behavior if your definition of some objective includes a stochastic variable and at the same time you specify it to be a linear or quadratic function. Note that this is incorrect problem formulation, but GTOpt cannot automatically detect it.

Changed in version 6.29: for objectives with @GTOpt/LinearityType set to "Linear", a strict requirement to train and use an internal linear model may be set using the GTOpt/RestoreAnalyticResponses option.

Changed in version 6.32: added the @GT/EvaluationLimit hint; deprecated the @GTOpt/ExpensiveEvaluations hint; for linear objectives, you can use the @GT/EvaluationLimit hint to increase the number of objective evaluations required when training an internal response model.

Changed in version 6.35: added the @GT/ObjectiveType hint.

Note

It is not recommended to set non-default @GTOpt/LinearityType and @GTOpt/EvaluationCostType for the same objective. This combination of hints is accepted, but may add ambiguity to GTOpt behavior. For example, if you require internal modeling of linear and quadratic responses (see GTOpt/RestoreAnalyticResponses), the GTOpt/MaximumExpensiveIterations option may be ignored for linear expensive objectives — accurate modeling of an objective may require more evaluations than allowed by GTOpt/MaximumExpensiveIterations.

Constraint Hints

• key: "@GTOpt/ConstraintAlpha", value: float in range \([0.0001, 0.9999]\); for example: 0.05; default: no value
• key: "@GTOpt/ConstraintType", value: "ExpectationConstraint" (default) or "ChanceConstraint"
• key: "@GTOpt/EvaluationCostType", value: "Cheap" (default) or "Expensive"
• key: "@GT/EvaluationLimit" (added in 6.32, updated in 6.39), value: integer in range \([1, 65535]\), 0 (deferred evaluation), -1, or "Auto" (no specific limit, default); -1 and "Auto" are the same
• key: "@GTOpt/ExpensiveEvaluations" — deprecated since 6.32, use "@GT/EvaluationLimit" instead
• key: "@GTOpt/LinearityType", value: "Generic" (default), "Linear", or "Quadratic"

Note

If @GTOpt/ConstraintType is set to "ChanceConstraint", then @GTOpt/ConstraintAlpha must also be set to a valid value since it has no default.

Changed in version 6.6: the @GTOpt/LinearityType hint is no longer ignored in robust optimization problems. However, GTOpt now assumes that constraints hinted as linear or quadratic do not depend on any stochastic variable. This can lead to unexpected behavior if your definition of some constraint includes a stochastic variable and, at the same time, you specify it to be a linear or quadratic function. Note that this is incorrect problem formulation, but GTOpt cannot detect it automatically.

Changed in version 6.29: for constraints with @GTOpt/LinearityType set to "Linear", a strict requirement to train and use an internal linear model may be set using the GTOpt/RestoreAnalyticResponses option.

Changed in version 6.32: added the @GT/EvaluationLimit hint; deprecated the @GTOpt/ExpensiveEvaluations hint; for linear constraints, you can use the @GT/EvaluationLimit hint to increase the number of constraint evaluations required when training an internal response model.

Note

It is not recommended to set non-default @GTOpt/LinearityType and @GTOpt/EvaluationCostType for the same constraint. This combination of hints is accepted, but may add ambiguity to GTOpt behavior. For example, if you require internal modeling of linear and quadratic responses (see GTOpt/RestoreAnalyticResponses), the GTOpt/MaximumExpensiveIterations option may be ignored for linear expensive constraints — accurate modeling of a constraint may require more evaluations than allowed by GTOpt/MaximumExpensiveIterations.

Note

Linear and quadratic constraints cannot have the chance constraint type. If you set @GTOpt/ConstraintType to "ChanceConstraint" for a linear or quadratic constraint, this @GTOpt/ConstraintType setting has no effect.

@GT/EvaluationLimit

Restricts the number of evaluations individually for a specific response (objective, constraint), including the evaluations of initial guess points. Can be used to defer certain response evaluations until you get the result. For a linear response, if GTOpt/RestoreAnalyticResponses is True or "Auto", sets the exact number of evaluations, overriding the limit set by the GTOpt/MaximumIterations option.

Key:"@GT/EvaluationLimit" Value:integer in range \([1, 65535]\), 0 (deferred evaluation), -1, or "Auto" Default:"Auto"

New in version 6.32.

Changed in version 6.39: when using concurrent response evaluations (GTOpt/ResponsesScalability), this hint limits the number of evaluation batches that request a specific response evaluation, rather than the total number of that specific response evaluations.

In addition to the overall limit on evaluations set by the GTOpt/MaximumIterations and GTOpt/MaximumExpensiveIterations options, you can use this hint to set evaluation limits individually on a per-response basis. If you use concurrent response evaluations (set the GTOpt/ResponsesScalability option to a value \(p\) greater than 1), the hint behavior is consistent with the abovementioned options behavior: it limits the number of evaluation batches, where each batch may contain up to \(p\) points requesting evaluations of that specific response. If @GT/EvaluationLimit for a given response is set to 0, GTOpt does not request any evaluations for that response (deferred evaluation).

Combinations of the @GT/EvaluationLimit hint with options that set the response evaluation limits work as follows:

• By setting @GT/EvaluationLimit to an appropriate positive number, you can set a lower limit than GTOpt/MaximumIterations and GTOpt/MaximumExpensiveIterations.

  Note that with the default setting for GTOpt/MaximumExpensiveIterations, GTOpt analyzes the problem’s properties (number of variables, responses, etc.) to automatically determine the overall limit on expensive evaluations. Then, it selects the lowest limit among @GT/EvaluationLimit, GTOpt/MaximumIterations, and the automatically determined GTOpt/MaximumExpensiveIterations. Since this behavior can be ambiguous, it is not advisable to use the @GT/EvaluationLimit hint in conjunction with the default GTOpt/MaximumExpensiveIterations option setting.

• If you enable internal modeling of linear and quadratic responses (set the GTOpt/RestoreAnalyticResponses option to True or keep it default), for linear responses you can use @GT/EvaluationLimit to require a certain number of evaluations when training the internal linear model. In this case, GTOpt evaluates the linear response exactly @GT/EvaluationLimit times, and the hint value is allowed to be higher than the GTOpt/MaximumIterations option value (the GTOpt/MaximumExpensiveIterations option has no effect on a linear response in this case even if the response is expensive; see the note above). This is useful when you want to improve accuracy of linear response modeling by increasing the training sample size — for example, if the linear response is noisy. It is not recommended to set a low @GT/EvaluationLimit for a linear response — GTOpt already aims to minimize the number of linear response evaluations by default, and if you set a restrictive limit, linear response modeling may fail.

• If @GT/EvaluationLimit for a given response is set to 0, GTOpt does not request any evaluations for that response — neither for new points nor for the initial sample points. This assumes that response evaluations are possible, though actual evaluation will be performed at a later stage, after obtaining the solution (deferred evaluation). Note that using deferred responses in optimization is very limiting, and GTOpt usually stops prematurely when given a problem with deferred responses.

• If the @GT/EvaluationLimit hint is not set, or set to one of the “auto” values (-1 or "Auto", default), the evaluation limit is controlled only by the GTOpt/MaximumIterations and GTOpt/MaximumExpensiveIterations options, except linear responses in the case when you enable the internal response modeling — in that case, the default evaluation limit for linear responses depends upon the number of design variables.

@GT/EvaluationLimit regards the evaluations required to obtain response values for the initial guess points in the same way as the GTOpt/MaximumIterations option: such evaluations count towards the limit specified by this hint. That is, for a non-linear response with the @GT/EvaluationLimit hint specified, the actual evaluation limit is the lowest of three values:

1. the limit set by GTOpt/MaximumIterations,
2. (for expensive responses only) the number of initial guesses plus the limit set by GTOpt/MaximumExpensiveIterations, and
3. the limit set by @GT/EvaluationLimit.

For linear responses specifically, the @GT/EvaluationLimit hint behavior depends on the response modeling settings (see GTOpt/RestoreAnalyticResponses):

• If internal response modeling is enabled, the actual evaluation limit is exactly the hint value, and that limit is always reached. Evaluations of initial guesses also count towards that limit.
• If internal response modeling is disabled, the actual evaluation limit for a linear response is determined by the general rules listed above (will be the lowest of applicable limits). Evaluations of initial guesses also count towards that limit as well.

Once the evaluation limit for a response is reached, GTOpt stops requesting its evaluations, setting the respective elements to 0 in the querymask it sends to the problem evaluation method. Proper handling of such selective evaluations requires a method that correctly parses the querymask; otherwise, the hint would have no effect. For this reason, if you want to use the @GT/EvaluationLimit hint, it is recommended to inherit your problem class from ProblemGeneric and implement the evaluate() method accordingly (see the method’s description for details).

For a linear response, if internal response modeling is enabled, the @GT/EvaluationLimit is reached, and obtained sample size appears too small to train an accurate linear model, GTOpt raises an exception.

@GTOpt/ExpensiveEvaluations

Restricts the number of evaluations individually for an expensive objective or constraint, including the evaluations of initial guess points.

Value:integer in range \([0, 65535]\), -1, or "Auto" Default:"Auto"

Deprecated since version 6.17: kept for version compatibility only.

The @GTOpt/ExpensiveEvaluations hint is deprecated and will be removed in future versions. Use the @GT/EvaluationLimit hint instead.

@GT/ObjectiveType

Specifies the kind of an optimization objective (minimization or maximization). Also used to specify evaluation responses — additional responses, which are not analyzed during optimization but are included in the evaluation history.

Key:"@GT/ObjectiveType" Value:"Minimize", "Maximize", "Evaluate", "Adaptive", or "Auto" Default:"Auto" (minimization objective)

New in version 6.35.

This hint changes the treatment of an objective response in optimization as follows:

• "Minimize" — an optimization objective to minimize.
• "Maximize" — an optimization objective to maximize.
• "Evaluate" — additional response, intended for satellite computations, which may be performed by the blackbox that evaluates objectives. Evaluation responses are not analyzed, but all their values returned by the blackbox are collected and stored to the problem evaluation history. Also, GTOpt requests such responses (sets a non-zero mask in the querymask argument to evaluate()) only in the optimal solution points. Evaluation responses are not supported in mean variance problems (ProblemMeanVariance).
• "Adaptive" — supported for compatibility with GTDoE; in optimization, this type is treated in the same way as evaluation responses.
• "Auto" (default) — in optimization, defaults to a minimization objective.

@GT/Resolution

Specifies the minimum significant change of a continuous or a stepped variable. Ignored for variables of other types.

Key:"@GT/Resolution" Value:positive floating point number Default:NaN (for continuous: any; for stepped: determined by step values)

New in version 6.29.

This hint adjusts handling of continuous and stepped variables in various optimization algorithms by specifying the minimum change that an algorithm can apply to a variable when studying the variable-response dependency.

If a design variable has certain precision, it is recommended to specify resolution for that variable, as it enables GTOpt to adjust precision of optimization algorithms accordingly, which often improves performance. Resolution should be based on the real, practical precision of a design variable.

Continuous variables have 0 (infinitely fine) resolution by default, meaning that any change greater than 0 is allowed, and problem responses are expected to be sensitive to such changes. Since practically this is rarely the case, consider specifying resolution for each continuous variable in the problem.

For stepped variables, GTOpt selects an appropriate resolution by default, calculating it from their step values. If steps are placed at regular intervals, keeping that default is recommended. In case of a stepped variable with irregular step intervals, you may want to set a specific resolution to improve algorithm stability.