7.4. Hint Reference¶

GTDoE hints specify types of variables and additional properties of responses in a DoE problem. Hints are usable only in build_doe() and only if you set up your DoE study using one of the GTDoE problem classes (gtdoe.ProblemGeneric and other).

You can specify hints in your problem class definition when adding variables, objectives, and constraints — see the hints 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(). Note that if using set_variable_hints() to set the type of a variable to discrete or categorical, you also have to specify levels for such a variable using set_variable_bounds().

The hints argument in the above methods is a dictionary with string keys and values. Keys are hint names, their values are hint values. For example, to add a discrete variable, in prepare_problem() call add_variable() as follows:

levels = (0.0, 0.2, 0.5, 0.7, 1.0)  # allowed values (levels) of your variable
hints = {"@GT/VariableType": "Discrete"}
add_variable(levels, name="x1", hints=hints)

Refer to the hint descriptions below for keys and values recognized in hints.

Variable hints
- @GT/FixedValue — sets a variable to constant (added in 6.35).
- @GT/Resolution — in Adaptive Design, may be used to adjust handling of stepped and continuous variables (added in 6.29).
- @GT/VariableType — specifies the type of a variable (added in 6.14, updated in 6.29).
Response hints
- @GT/EvaluationLimit — restricts the number of evaluations individually for a specific response; also can be used to require a certain number of linear response evaluations, if linear response modeling is enabled (added in 6.32, updated in 6.39).
- @GTOpt/EvaluationCostType — marks responses as computationally cheap or expensive (added in 6.14).
- @GTOpt/LinearityType — specifies that a response is linear or quadratic (added in 6.14, updated in v2024.03).
- @GT/ObjectiveType — changes objective response treatment (added in 6.35).

@GT/FixedValue

Freezes a variable, giving it a constant value in the generated DoE.

Key: "@GT/FixedValue"

Value: depends on the type of variable

Default: none, value required

New in version 6.35.

A variable of any type can be frozen, giving it a constant value in the generated DoE. For a continuous variable, you may specify a constant value that is out of variable bounds. For other types of variables, the value you specify must be valid according to levels defined for that variable (for discrete and categorical types) or steps (for a stepped variable).

@GT/Resolution

Adjusts handling of stepped and continuous variables in the Adaptive Design technique by specifying the minimum significant change of a 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.

Note

This hint is ignored by all GTDoE techniques except Adaptive Design.

This hint is supported in GTDoE primarily for compatibility with GTOpt problem definitions. It is ignored by all techniques except Adaptive Design, where it may be used to specify the minimum change that an algorithm can apply to a variable when studying the variable-response dependency.

If you set resolution, it should be based on the real, practical precision of a design variable. For continuous variables, the default means that any change greater than 0 is allowed. For stepped variables, GTDoE 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.

@GT/VariableType

Specifies the type of a design variable.

Key: "@GT/VariableType"

Value: "Continuous", "Discrete", "Stepped", or "Categorical"

Default: "Continuous"

New in version 6.14.

Changed in version 6.29: added the stepped variable type.

This hint sets the type of a design variable in a DoE problem definition:

"Continuous" — a generic continuous variable. Variables are considered continuous by default, so you are free to omit the type hint when adding a continuous variable.

"Discrete" — a discontinuous numeric variable that can take any value from the predefined set of allowed values (levels).

"Stepped" — a special kind of a continuous variable that is bound to a certain grid.

"Categorical" — a special type of variable that has a finite number of possible values (categories, or levels) and does not assume any numerical meaning, order or metrics.

See section Types of Variables for more details on different types of variables and their support in GTDoE techniques.

@GT/EvaluationLimit

Restricts the number of evaluations individually for a specific response (objective, constraint), including the evaluations of initial sample points. Can be used to defer certain response evaluations until you get the result. In Adaptive Design only, if linear response modeling is enabled (GTDoE/AdaptiveDesign/RestoreAnalyticResponses is True or "Auto"), this hint sets the exact number of evaluations for a linear response, and that per-response setting overrides the limit set by GTDoE/AdaptiveDesign/MaximumIterations.

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.35: space-filling DoE techniques no longer ignore this hint; evaluation limits it specifies now apply when evaluating responses for the resulting DoE points.

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

In all DoE techniques except Adaptive Design, this hint sets a hard limit on the number of specific response evaluations. Once the limit is reached, GTDoE stops requesting evaluations of that response; if the number of resulting DoE points is greater than the limit, remaining response values are set to None. If @GT/EvaluationLimit for a given response is set to 0, GTDoE does not request any evaluations for that response (deferred evaluation).

In Adaptive Design, you can use @GT/EvaluationLimit to set evaluation limits individually on a per-response basis, in addition to the overall evaluation limit set by the GTDoE/AdaptiveDesign/MaximumIterations and GTDoE/AdaptiveDesign/MaximumExpensiveIterations options. If you use concurrent response evaluations (set the GTDoE/ResponsesScalability option to a value \(p\) greater than 1), the hint behavior is consistent with the options behavior: it limits the number of evaluation batches, where each batch may contain up to \(p\) points requesting evaluations of that specific response.

In Adaptive Design, 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 GTDoE/AdaptiveDesign/MaximumIterations and GTDoE/AdaptiveDesign/MaximumExpensiveIterations.

Note that with the default setting for GTDoE/AdaptiveDesign/MaximumExpensiveIterations, GTDoE 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, GTDoE/AdaptiveDesign/MaximumIterations, and the automatically determined GTDoE/AdaptiveDesign/MaximumExpensiveIterations. Since this behavior can be ambiguous, it is not advisable to use the @GT/EvaluationLimit hint in conjunction with the default GTDoE/AdaptiveDesign/MaximumExpensiveIterations option setting.

If you enable internal modeling of linear and quadratic responses (set the GTDoE/AdaptiveDesign/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, GTDoE evaluates the linear response exactly @GT/EvaluationLimit times, and the hint value is allowed to be higher than the GTDoE/AdaptiveDesign/MaximumIterations or GTDoE/AdaptiveDesign/MaximumExpensiveIterations option value. 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 — GTDoE 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, GTDoE does not request any evaluations for that response. This assumes that response evaluations are possible, though actual evaluation will be performed at a later stage, after obtaining the result DoE (deferred evaluation). The result can then be used as an initial sample in the next run of the same task. Note that GTDoE does not request deferred response evaluations for the initial sample points, if those response values are missing from the sample.

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 GTDoE/AdaptiveDesign/MaximumIterations and GTDoE/AdaptiveDesign/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.

In Adaptive Design, @GT/EvaluationLimit regards the evaluations required to obtain response values for the initial guess points in the same way as the GTDoE/AdaptiveDesign/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:

the limit set by GTDoE/AdaptiveDesign/MaximumIterations,

(for expensive responses only) the number of initial guesses plus the limit set by GTDoE/AdaptiveDesign/MaximumExpensiveIterations, and

the limit set by @GT/EvaluationLimit.

For linear responses in Adaptive Design specifically, the @GT/EvaluationLimit hint behavior depends on the response modeling settings (see GTDoE/AdaptiveDesign/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 all applicable limits). Evaluations of initial guesses also count towards that limit as well.

Once the evaluation limit for a response is reached, GTDoE 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).

In Adaptive Design with internal response modeling enabled, if the @GT/EvaluationLimit for a linear response is reached but the obtained sample appears too small to train an accurate linear model, GTDoE raises an exception.

@GTOpt/EvaluationCostType

Marks a response as computationally cheap or expensive.

Key: "@GTOpt/EvaluationCostType"

Value: "Cheap" or "Expensive"

Default: "Cheap"

New in version 6.14.

The Adaptive Design technique uses surrogate-based methods (similar to Surrogate Based Optimization), which make a distinction between computationally cheap and expensive responses. Other GTDoE techniques ignore this hint.

Cheap responses may be evaluated an unlimited number of times by default. Adaptive Design does not aim to limit the number of cheap response evaluations. This limit may be imposed manually, using the GTDoE/AdaptiveDesign/MaximumIterations, although its value should be relatively high (of order \(10^3\) or greater). Setting the evaluation limit for computationally cheap responses too low may cause an abrupt stop in the Adaptive Design algorithm, which does not raise an error but often decreases the result quality significantly.

Expensive responses are always expected to have a finite evaluation limit. This limit is set according to the GTDoE/AdaptiveDesign/MaximumExpensiveIterations option value. If this option does not set a specific limit, GTDoE determines it automatically. The automatic limit is finite but can vary depending on the problem properties.

@GTOpt/LinearityType

Specifies that a response is linear or quadratic and enables the internal modeling of this response.

Key: "@GTOpt/LinearityType"

Value: "Generic", "Linear", or "Quadratic"

Default: "Generic"

New in version 6.14.

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 GTDoE/AdaptiveDesign/RestoreAnalyticResponses option.

Changed in version 6.32: for linear responses, you can use the @GT/EvaluationLimit hint to increase the number of response evaluations required when training an internal response model.

Changed in version v2024.03: all GTDoE techniques now recognize the linearity hint and enable the internal modeling of linear responses.

GTDoE supports internal modeling of:

responses that are linear functions of variables — for all techniques (partial support in Adaptive Design of Experiments), and

quadratic responses — for Adaptive Design only.

Space-filling DoE techniques generate the full DoE prior to requesting any response evaluations. Once the full space-filling DoE is generated, GTDoE selects a subset of it to use as the training sample for linear response modeling. For the points of that subset, linear response values are requested from the blackbox to obtain the evaluated subset. GTDoE then tests whether a linear model can fit the evaluated response data with enough accuracy, with the following possible outcomes:

Positive: the response-input dependency in the evaluated subset is approximately linear, so the fit is possible. GTDoE creates a linear response model, which it further uses to evaluate that response, and no longer requests values of that response from the blackbox.

Negative: there is no fit — for example, the response data is too noisy, or the response is actually a non-linear function. GTDoE issues a warning to the log and continues to request values of that response from the blackbox.

The Adaptive Design of Experiments technique supports linear modeling for all kinds of responses except the adaptation objectives, which are always evaluated through the blackbox, even if hinted linear. Otherwise the behavior of this technique regarding linear responses is similar to the space-filling DoE techniques behavior: it first generates the full DoE (the sample inputs) — albeit using the adaptive generation method, which analyzes the behavior of adaptation objectives — then models and calculates the linear responses in the same manner as the space-filling DoE techniques, then requests the remaining response evaluations from the blackbox.

In Adaptive Design, modeling is supported for linear and quadratic responses, and they are handled according to the GTDoE/AdaptiveDesign/RestoreAnalyticResponses setting.

All of the modeling features noted above are completely disabled for generic responses, which do not assume any specific dependency type. Responses are considered generic by default, so you are free to omit the @GTOpt/LinearityType hint when adding a generic response.

@GT/ObjectiveType

Changes treatment of an objective response, depending on the applied GTDoE technique.

Key: "@GT/ObjectiveType"

Value: "Adaptive", "Evaluate", "Maximize", "Minimize", or "Auto"

Default: "Auto" (adaptive response in Adaptive DoE and Adaptive Design, evaluation response in other DoE techniques)

New in version 6.35.

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

"Adaptive" — an adaptation objective for the Adaptive Design of Experiments and Adaptive Design techniques. Other DoE techniques treat this response type in the same way as evaluation responses.

"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. GTDoE generally requests such responses (sets a non-zero mask in the querymask argument to evaluate()) in all DoE points included into the final result.

"Minimize", "Maximize" — same as "Evaluate" but with additional post-processing: GTDoE selects Pareto-optimal points from the resulting DoE with regard to such responses, and you can get those points from solutions() — for example, solutions(filter_type=["new", "optimal"]) to get optimal points that were not already found in the initial sample.

"Auto" (default) — in Adaptive Design of Experiments and Adaptive Design, defaults to an adaptation objective. In other techniques, defaults to an evaluation objective.