Function Evaluations

ropt.evaluator.EvaluatorContext dataclass

Capture additional details for the function evaluator.

Function evaluators (see Evaluator) primarily receive variable vectors to evaluate objective and constraint functions. However, they may also benefit from additional information to optimize their calculations. This EvaluatorContext object provides that supplementary information.

Specifically, it provides:

• The context object for the current optimization run.
• A boolean vector (active) indicating which variable rows require evaluation.
• The realization index for each variable vector. This can be used to determine the correct function from an ensemble to use with each variable vector.
• The perturbation index for each variable vector (if applicable). A value less than 0 indicates that the vector is not a perturbation.

Attributes:

Name	Type	Description
context	EnOptContext	Context of the optimizer.
active	NDArray[bool_]	Indicates which variable rows require evaluation.
realizations	NDArray[intc]	Realization numbers for each requested evaluation.
perturbations	NDArray[intc] | None	Perturbation numbers for each requested evaluation. A value less than 0 indicates that the vector is not a perturbation.

get_active_evaluations

get_active_evaluations(array: NDArray[T]) -> NDArray[T]

Filter an array based on the active property.

This is a utility method, which can be used if only the active property is used to exclude variable rows that are inactive, i.e. where none of the objects or constraints are needed.

This method filters a one- or two-dimensional array by retaining only those entries or rows that correspond to active. The activity of realizations is determined by the self.active boolean array (where True indicates active).

If self.active is None (indicating that all variable rows are to be considered active), no filtering is applied, and the original input is returned.

Parameters:

Name	Type	Description	Default
array	NDArray[T]	The array to filter.	required

Returns:

Type	Description
NDArray[T]	The filtered results.

insert_inactive_results

insert_inactive_results(
    array: NDArray[T], *, fill_value: float = 0.0
) -> NDArray[T]

Expand an array by inserting fill values for inactive variables.

This is a utility method, which can be used if only the active property is used to exclude variable rows that are fully inactive.

This method takes an array and expands it to its original dimensions by inserting a specified fill_value at positions corresponding to inactive rows. If the array is one-dimensional, zero entries are inserted, if it is two-dimensional rows of zero values are inserted.

If self.active is None (implying all rows were considered active or no filtering was applied), the input array is returned unchanged.

Parameters:

Name	Type	Description	Default
array	NDArray[T]	The array to expand.	required
fill_value	float	The value to insert for inactive entries.	0.0

Returns:

Type	Description
NDArray[T]	An expanded array matching the original number of variables.

ropt.evaluator.EvaluatorResult dataclass

Store the results of a function evaluation.

This class stores the results of evaluating objective and constraint functions for a set of variable vectors.

The objectives and constraints are stored as matrices. Each column in these matrices corresponds to a specific objective or constraint, and each row corresponds to a variable vector.

When the evaluator is asked to evaluate functions, some variable vectors may be marked as inactive. The results for these inactive vectors should be set to zero. All active variable vectors should be evaluated. If an evaluation fails for any reason, the corresponding values should be set to numpy.nan.

A batch_id can be set to identify this specific set of evaluation results.

The evaluation_info dictionary can store additional metadata for each evaluation. This information is not used internally by ropt and can have an arbitrary structure, to be interpreted by the application. This can be used, for example, to uniquely identify the results calculated for each variable vector, allowing them to be linked back to their corresponding input vectors.

Parameters:

Name	Type	Description	Default
objectives	NDArray[float64]	The calculated objective values.	required
constraints	NDArray[float64] | None	Optional calculated constraint values.	None
batch_id	int | None	Optional batch ID to identify this set of results.	None
evaluation_info	dict[str, NDArray[Any]]	Optional info for each evaluation.	dict()

ropt.evaluator.EvaluatorCallback

Bases: Protocol

Defines the call signature for evaluator callbacks.

Events handlers define a callback to handler events emitted during the optimization process.

__call__

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

Handle an event.

Parameters:

Name	Type	Description	Default
variables	NDArray[float64]	The variables to pass to the evaluation function.	required
context	EvaluatorContext	The evaluator context to pass.	required

Returns:

Type	Description
EvaluatorResult	The results of the evaluation.