Evaluator Classes

The ropt.evaluation module defines the data structures exchanged between ropt and user-provided evaluation functions: an input context describing which rows must be evaluated, an output container for the objective and constraint values, and the protocol that user callables must follow.

For detailed usage, including examples of handling inactive rows and partial failures, see Writing Evaluation Callbacks. For higher-level Evaluator classes used by the workflow framework, see Workflow Evaluator Classes.

ropt.evaluation.EvaluationBatchContext dataclass

Per-batch metadata passed to evaluator functions.

See Writing Evaluation Callbacks for usage details and examples.

Attributes:

Name	Type	Description
context	EnOptContext	The EnOptContext for the run.
active	NDArray[bool_]	Boolean array indicating which rows require evaluation.
realizations	NDArray[intc]	Realization index for each row.
perturbations	NDArray[intc] | None	Perturbation index for each row (< 0 means unperturbed).
batch_id	int	Integer identifying the current evaluation batch.

get_active_evaluations

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

Return only the rows of array where active is True.

Parameters:

Name	Type	Description	Default
array	NDArray[T]	A 1-D or 2-D array with one entry/row per variable vector.	required

Returns:

Type	Description
NDArray[T]	The subset of rows corresponding to active evaluations.

insert_inactive_results

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

Expand a filtered array back to full size, filling inactive rows.

Inserts fill_value at positions where active is False, restoring the array to its original number of rows.

Parameters:

Name	Type	Description	Default
array	NDArray[T]	The filtered array (output of get_active_evaluations).	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 rows.

ropt.evaluation.EvaluationBatchResult dataclass

Results of a function evaluation batch.

Stores objective values (and optional constraint values) for a batch of variable vectors. Inactive rows should be set to zero; failed active rows should be set to numpy.nan.

The batch_id field defaults to 0. If you do not need to distinguish between batches, leave it unset — all results will be labelled batch 0. To get auto-incrementing IDs managed by the framework, pass a BatchIdCounter (or any Callable[[], int]) to the batch_id_callback argument of FunctionEvaluator or AsyncEvaluator. For raw BatchEvaluator callbacks, set batch_id yourself.

See Writing Evaluation Callbacks for detailed conventions and examples.

Parameters:

Name	Type	Description	Default
objectives	NDArray[float64]	Objective values, shape (n_rows, n_objectives).	required
constraints	NDArray[float64] | None	Optional constraint values, shape (n_rows, n_constraints).	None
batch_id	int	Integer identifying this evaluation batch.	0
metadata	dict[str, NDArray[Any]]	Optional dict of per-row metadata (not used internally by ropt).	dict()

ropt.evaluation.EvaluationBatchCallback

Bases: Protocol

Defines the call signature for batch evaluation callbacks.

__call__

__call__(
    variables: NDArray[float64],
    context: EvaluationBatchContext,
) -> EvaluationBatchResult

Evaluate the given variables within the provided context.

Parameters:

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

Returns:

Type	Description
EvaluationBatchResult	The results of the evaluation.