Evaluators

ropt.plugins.evaluator.default.DefaultEvaluatorPlugin

Bases: EvaluatorPlugin

The default plugin for creating evaluators.

This plugin acts as a factory for the standard evaluator implementations provided by ropt.

Supported Evaluators:

function_evaluator: Creates a DefaultFunctionEvaluator instance, which uses function calls to calculated individual objectives and constraints.

ropt.plugins.evaluator._function_evaluator.DefaultFunctionEvaluator

Bases: Evaluator

An evaluator that forwards calls to an evaluator function.

This class acts as an adapter, allowing a standard Python callable (which matches the signature of the eval method) to be used as an Evaluator within an optimization workflow.

It is initialized with an evaluator callable. When the eval method of this class is invoked, it simply delegates the call, along with all arguments, to the wrapped evaluator function.

init

__init__(*, callback: EvaluatorCallback) -> None

Initialize the DefaultFunctionEvaluator.

Parameters:

Name	Type	Description	Default
`callback`	`EvaluatorCallback`	The callable that will perform the actual evaluation.	required

eval

eval(
    variables: NDArray[float64], context: EvaluatorContext
) -> EvaluatorResult

Forward the evaluation call to the wrapped evaluator function.

Parameters:

Name	Type	Description	Default
`variables`	`NDArray[float64]`	The matrix of variables to evaluate.	required
`context`	`EvaluatorContext`	The evaluation context.	required

Returns:

Type	Description
`EvaluatorResult`	The result of calling the wrapped evaluator function.

ropt.plugins.evaluator.cached_evaluator.DefaultCachedEvaluator

Bases: Evaluator

An evaluator that caches results to avoid redundant computations.

This evaluator attempts to retrieve previously computed function results from a cache before delegating to another evaluator. The cache is populated from FunctionResults objects stored by EventHandler instances specified as sources.

When an evaluation is requested, for each variable vector and its corresponding realization, this evaluator searches through the results attribute of its sources. If a FunctionResults object is found where the variables match the input (within a small tolerance) and the realization also matches, the cached objectives and constraints from that FunctionResults object are used.

If some, but not all, requested evaluations are found in the cache, this evaluator will mark the cached ones as inactive for the next evaluator in the chain and then call that evaluator to compute only the missing results. The final combined results (cached and newly computed) are then returned.

This is particularly useful in scenarios where the same variable sets might be evaluated multiple times, for example, in iterative optimization algorithms or when restarting optimizations.

init

__init__(
    *,
    evaluator: Evaluator,
    sources: list[EventHandler] | None = None,
) -> None

Initialize the DefaultCachedEvaluator.

The sources argument should be a sequence of EventHandler instances. These handlers are expected to store FunctionResults in their ["results"] attribute.

Parameters:

Name	Type	Description	Default
`evaluator`	`Evaluator`	The evaluator to cache.	required
`sources`	`list[EventHandler] \| None`	`EventHandler` instances for retrieving cached results.	`None`

eval_cached

eval_cached(
    variables: NDArray[float64], context: EvaluatorContext
) -> tuple[
    EvaluatorResult, dict[int, tuple[int, FunctionResults]]
]

Evaluate objective and constraint functions, utilizing a cache.

This method implements the core evaluation logic. It returns not only the evaluation results but also the function results that were retrieved from cache. The eval method in this class does not utilize these indices. However, derived classes can overload eval and use this information to add further details to the results, such as populating the evaluation_info attribute of an EvaluatorResult.

The cache hits that are returned consists of a dictionary where the keys are the indices of the variable vectors that were found in the cache, and the values are tuples containing the realization index of the cached vectors and the corresponding FunctionResults object. This allows the caller to know which evaluations were retrieved from cache and which were computed anew. The cached evaluations can then be retrieved from the FunctionResults object, using the realization index.

Note

If the optimization was initialized with realization names in the configuration, these are used to match the realizations of the requested evaluations, with those in the cached results. This means that the results may originate from a different optimization run, as long as the realization names are still valid. However, in this case the results used for finding cached values must also store the realization names, otherwise the cached results will not be found.

If the configuration does not contain realization names, the realization indices are used to match the realizations of the requested evaluations. In this case the indices of the realizations in the cached results must match those of the requested evaluations, i.e. they must have been specified in the same order in the respective configurations.

Parameters:

Name	Type	Description	Default
`variables`	`NDArray[float64]`	Matrix of variables to evaluate (each row is a vector).	required
`context`	`EvaluatorContext`	The evaluation context.	required

Returns:

Type	Description
`tuple[EvaluatorResult, dict[int, tuple[int, FunctionResults]]]`	An `EvaluatorResult` and the cache hits.

eval

eval(
    variables: NDArray[float64], context: EvaluatorContext
) -> EvaluatorResult

Evaluate objective and constraint functions, utilizing a cache.

For each input variable vector and its realization, this method first attempts to find a matching result in the cache provided by its sources.

If a result is found in the cache, it's used directly. If not, the evaluation is delegated to the stored evaluator. The context.active array is updated to indicate to the subsequent evaluator which evaluations are still pending; evaluations found in the cache are marked as inactive.

Parameters:

Name	Type	Description	Default
`variables`	`NDArray[float64]`	Matrix of variables to evaluate (each row is a vector).	required
`context`	`EvaluatorContext`	The evaluation context.	required

Returns:

Type	Description
`EvaluatorResult`	An `EvaluatorResult` with calculated or cached values.

add_sources

add_sources(
    sources: EventHandler | Sequence[EventHandler],
) -> None

Add one or more EventHandler sources to the evaluator.

This method allows adding additional sources of cached results to the evaluator. The sources are expected to be EventHandler instances that store FunctionResults.

Parameters:

Name	Type	Description	Default
`sources`	`EventHandler \| Sequence[EventHandler]`	`EventHandler` instances to add as a source.	required

remove_sources

remove_sources(
    sources: EventHandler | Sequence[EventHandler],
) -> None

Remove one or more EventHandler sources from the evaluator.

This method allows removing previously added sources of cached results from the evaluator.

Parameters:

Name	Type	Description	Default
`sources`	`EventHandler \| Sequence[EventHandler]`	`EventHandler` instances to remove as a source.	required