Evaluation Results

Every batch evaluation produces a tuple of Results objects: a FunctionResults for objective and constraint values, and/or a GradientResults for gradient estimates. Each is a frozen container of ResultField sub-objects holding NumPy arrays with axis-name metadata.

See Working with Results for a tour of the access patterns.

ropt.results

Data classes for storing intermediate optimization results.

See Working with Results for a narrative overview of the result hierarchy, axis metadata, domain transforms, and pandas export.

ropt.results.Results dataclass

Bases: ABC

Abstract base class for optimization results.

Subclassed by FunctionResults and GradientResults.

See Working with Results for a narrative overview.

Attributes:

Name	Type	Description
batch_id	int	Identifier for the evaluation batch.
metadata	dict[str, Any]	Dictionary of additional information (not used internally).
names	dict[str, tuple[str | int, ...]]	Mapping from AxisName to label tuples for DataFrame export.

to_dataframe

to_dataframe(
    field_name: str,
    select: Iterable[str],
    unstack: Iterable[AxisName] | None = None,
) -> pd.DataFrame

Export a field to a pandas DataFrame.

Exports the sub-fields of field_name as columns, named after the sub-field. Multi-dimensional sub-fields are stacked into rows indexed by a multi-index derived from the field's axis metadata; index levels are labeled using the names mapping (numeric indices if absent). batch_id is always prepended to the index. The unstack argument pivots selected axes into columns, producing tuple column names of the form (sub-field, label, ...).

See Working with Results for further details and examples.

Parameters:

Name	Type	Description	Default
field_name	str	The field to export.	required
select	Iterable[str]	Sub-fields to include.	required
unstack	Iterable[AxisName] | None	Axes to pivot into columns (default: none).	None

Returns:

Type	Description
DataFrame	A DataFrame with sub-fields as columns and axis indices as rows.

Raises:

Type	Description
NotImplementedError	If the pandas module is not installed.
AttributeError	If the field name is invalid.

transform_from_optimizer abstractmethod

transform_from_optimizer(context: EnOptContext) -> Results

Transform results from the optimizer domain to the user domain.

Reverses variable, objective, and constraint transforms applied during optimization, restoring values to the user-defined domain.

Parameters:

Name	Type	Description	Default
context	EnOptContext	The context used by the source of the results.	required

Returns:

Type	Description
Results	A new Results object in the user domain.

ropt.results.ResultField dataclass

Base class for result field containers that carry axis metadata.

See Working with Results for how axis metadata is used.

get_axes classmethod

get_axes(name: str) -> tuple[AxisName, ...]

Return the axis metadata for a named field.

Parameters:

Name	Type	Description	Default
name	str	The name of the field within this dataclass.	required

Returns:

Type	Description
tuple[AxisName, ...]	A tuple of AxisName values.

Raises:

Type	Description
ValueError	If the field name is not recognized.

ropt.results.FunctionResults dataclass

Bases: Results

Results of a function evaluation batch.

See Working with Results for usage details.

Attributes:

Name	Type	Description
evaluations	FunctionEvaluations	Per-realization evaluation data.
realizations	Realizations	Realization activity and weights.
functions	Functions | None	Aggregated function values, or None if all failed.
constraint_info	ConstraintInfo | None	Constraint differences and violations, if applicable.

transform_from_optimizer

transform_from_optimizer(
    context: EnOptContext,
) -> FunctionResults

Transform results from optimizer space to user space.

This applies inverse transformations to all transformable sub-fields (evaluations, functions, and constraint_info when present). Realization metadata is passed through unchanged.

Parameters:

Name	Type	Description	Default
context	EnOptContext	The context used by the source of the results.	required

Returns:

Type	Description
FunctionResults	The transformed results.

ropt.results.GradientResults dataclass

Bases: Results

Results of a gradient evaluation batch.

See Working with Results for usage details.

Attributes:

Name	Type	Description
evaluations	GradientEvaluations	Perturbed-variable evaluation data.
realizations	Realizations	Realization activity and weights.
gradients	Gradients | None	Aggregated gradient values, or None if estimation failed.

transform_from_optimizer

transform_from_optimizer(
    context: EnOptContext,
) -> GradientResults

Transform results from optimizer space to user space.

This applies inverse transformations to transformable sub-fields (evaluations and gradients when present). Realization metadata is passed through unchanged.

Parameters:

Name	Type	Description	Default
context	EnOptContext	The context used by the source of the results.	required

Returns:

Type	Description
GradientResults	The transformed results.

ropt.results.Functions dataclass

Bases: ResultField

Aggregated objective and constraint function values.

See Working with Results for usage details.

Result descriptions

Weighted ObjectiveObjectivesConstraints

target_objective: The overall objective calculated as a weighted sum over the, possibly transformed, objectives. This is a single floating point value. It is defined as a numpy array of dimensions 0, hence it has no axes:

• Shape: \(()\)
• Axis type: None

objectives: The calculated objective function values. This is a one-dimensional array of floating point values:

• Shape \((n_o,)\), where:
  • \(n_o\) is the number of objectives.
• Axis type:
  • AxisName.OBJECTIVE

constraints: The calculated constraint function values. This is a one-dimensional array of floating point values:

• Shape \((n_c,)\), where:
  • \(n_c\) is the number of constraints.
• Axis type:
  • AxisName.NONLINEAR_CONSTRAINT

Attributes:

Name	Type	Description
target_objective	NDArray[float64]	The target objective value used by the optimizer.
objectives	NDArray[float64]	The value of each individual objective.
constraints	NDArray[float64] | None	The value of each individual constraint, if present.

create classmethod

create(
    target_objective: NDArray[float64],
    objectives: NDArray[float64],
    constraints: NDArray[float64] | None = None,
) -> Functions

Create a Functions object from pre-aggregated function values.

Parameters:

Name	Type	Description	Default
target_objective	NDArray[float64]	The target objective used by the optimizer.	required
objectives	NDArray[float64]	Objective function values.	required
constraints	NDArray[float64] | None	Constraint function values.	None

Returns:

Type	Description
Functions	A new Functions object.

ropt.results.Gradients dataclass

Bases: ResultField

Aggregated objective and constraint gradients.

See Working with Results for usage details.

Result descriptions

Weighted Objective GradientObjective GradientsConstraint Gradients

target_objective: The gradient of the target objective with respect to each variable:

• Shape: \((n_v,)\), where:
  • \(n_v\) is the number of variables.
• Axis type:
  • AxisName.VARIABLE

objectives: The calculated gradients of each objective with respect to each variable. This is a two-dimensional array of floating point values:

• Shape \((n_o, n_v)\), where:
  • \(n_o\) is the number of objectives.
  • \(n_v\) is the number of variables.
• Axis types:
  • AxisName.OBJECTIVE
  • AxisName.VARIABLE

constraints: The calculated gradients of each nonlinear constraint with respect to each variable. This is a two-dimensional array of floating point values:

• Shape \((n_c, n_v)\), where:
  • \(n_c\) is the number of constraints.
  • \(n_v\) is the number of variables.
• Axis types:
  • AxisName.NONLINEAR_CONSTRAINT
  • AxisName.VARIABLE

Attributes:

Name	Type	Description
target_objective	NDArray[float64]	The gradient of the target objective.
objectives	NDArray[float64]	The gradient of each individual objective.
constraints	NDArray[float64] | None	The gradient of each individual constraint, if present.

create classmethod

create(
    target_objective: NDArray[float64],
    objectives: NDArray[float64],
    constraints: NDArray[float64] | None = None,
) -> Gradients

Create a Gradients object from pre-aggregated gradient values.

Parameters:

Name	Type	Description	Default
target_objective	NDArray[float64]	The gradient of the target objective.	required
objectives	NDArray[float64]	Objective gradients.	required
constraints	NDArray[float64] | None	Constraint gradients.	None

Returns:

Type	Description
Gradients	A new Gradients object.

ropt.results.FunctionEvaluations dataclass

Bases: ResultField

Per-realization objective and constraint values for an evaluation batch.

See Working with Results for usage details.

Result descriptions

VariablesObjectivesConstraintsMetadata

variables: The vector of variable values at which the functions were evaluated:

• Shape: \((n_v,)\), where:
  • \(n_v\) is the number of variables.
• Axis type:
  • AxisName.VARIABLE

objectives: The calculated objective function values for each realization. This is a two-dimensional array of floating point values where each row corresponds to a realization and each column corresponds to an objective:

• Shape \((n_r, n_o)\), where:
  • \(n_r\) is the number of realizations.
  • \(n_o\) is the number of objectives.
• Axis types:
  • AxisName.REALIZATION
  • AxisName.OBJECTIVE

constraints: The calculated constraint function values for each realization. Only provided if non-linear constraints are defined. This is a two-dimensional array of floating point values where each row corresponds to a realization and each column corresponds to a constraint:

• Shape \((n_r, n_c)\), where:
  • \(n_r\) is the number of realizations.
  • \(n_c\) is the number of constraints.
• Axis types:
  • AxisName.REALIZATION
  • AxisName.NONLINEAR_CONSTRAINT

metadata: Optional metadata associated with each realization, potentially provided by the evaluator. If provided, each value in the metadata dictionary must be a one-dimensional array of arbitrary type supported by numpy (including objects):

• Shape: \((n_r,)\), where:
  • \(n_r\) is the number of realizations.
• Axis type:
  • AxisName.REALIZATION

Metadata data type.

The data type of the metadata fields is not fixed. Each field in the metadata dictionary can have its own data type, which must be a one-dimensional array of any type supported by numpy, including object arrays. This allows for maximum flexibility in the kind of metadata that can be included, such as strings, integers, floats, or even complex objects.

Attributes:

Name	Type	Description
variables	NDArray[float64]	The variable vector.
objectives	NDArray[float64]	The objective function values for each realization.
constraints	NDArray[float64] | None	The constraint function values for each realization.
metadata	dict[str, NDArray[Any]]	Optional metadata for each evaluated realization.

create classmethod

create(
    variables: NDArray[float64],
    objectives: NDArray[float64],
    constraints: NDArray[float64] | None = None,
    metadata: dict[str, NDArray[Any]] | None = None,
) -> FunctionEvaluations

Create a FunctionEvaluations object with the given data.

Parameters:

Name	Type	Description	Default
variables	NDArray[float64]	The unperturbed variable vector.	required
objectives	NDArray[float64]	The objective functions for each realization.	required
constraints	NDArray[float64] | None	The constraint functions for each realization.	None
metadata	dict[str, NDArray[Any]] | None	Optional info for each evaluation.	None

Returns:

Type	Description
FunctionEvaluations	A new FunctionEvaluations object.

ropt.results.GradientEvaluations dataclass

Bases: ResultField

Per-realization evaluation data for perturbed variables.

See Working with Results for usage details.

Result descriptions

VariablesPerturbed VariablesPerturbed ObjectivesPerturbed ConstraintsMetadata

variables: The vector of unperturbed variable values:

• Shape: \((n_v,)\), where:
  • \(n_v\) is the number of variables.
• Axis type:
  • AxisName.VARIABLE

perturbed_variables: A three-dimensional array of perturbed variable values for each realization and perturbation:

• Shape: \((n_r, n_p, n_v)\), where:
  • \(n_r\) is the number of realizations.
  • \(n_p\) is the number of perturbations.
  • \(n_v\) is the number of variables.
• Axis type:
  • AxisName.REALIZATION
  • AxisName.PERTURBATION
  • AxisName.VARIABLE

perturbed_objectives: A three-dimensional array of perturbed calculated objective function values for each realization and perturbation:

• Shape \((n_r, n_p, n_o)\), where:
  • \(n_r\) is the number of realizations.
  • \(n_p\) is the number of perturbations.
  • \(n_o\) is the number of objectives.
• Axis types:
  • AxisName.REALIZATION
  • AxisName.PERTURBATION
  • AxisName.OBJECTIVE

perturbed_constraints: A three-dimensional array of perturbed calculated non-linear constraint values for each realization and perturbation:

• Shape \((n_r, n_p, n_c)\), where:
  • \(n_r\) is the number of realizations.
  • \(n_p\) is the number of perturbations.
  • \(n_c\) is the number of constraints.
• Axis types:
  • AxisName.REALIZATION
  • AxisName.PERTURBATION
  • AxisName.NONLINEAR_CONSTRAINT

metadata: Optional metadata associated with each realization, potentially provided by the evaluator. If provided, each value in the metadata dictionary must be a two-dimensional array of arbitrary type supported by numpy (including objects):

• Shape: \((n_r, n_p)\), where:
  • \(n_r\) is the number of realizations.
  • \(n_p\) is the number of perturbations.
• Axis types:
  • AxisName.REALIZATION
  • AxisName.PERTURBATION

Metadata data type.

The data type of the metadata fields is not fixed. Each field in the metadata dictionary can have its own data type, which must be a two-dimensional array of any type supported by numpy, including object arrays. This allows for maximum flexibility in the kind of metadata that can be included, such as strings, integers, floats, or even complex objects.

Attributes:

Name	Type	Description
variables	NDArray[float64]	The unperturbed variable vector.
perturbed_variables	NDArray[float64]	The perturbed variable values for each realization and perturbation.
perturbed_objectives	NDArray[float64]	The objective function values for each realization and perturbation.
perturbed_constraints	NDArray[float64] | None	The constraint function values for each realization and perturbation.
metadata	dict[str, NDArray[Any]]	Optional metadata for each evaluated realization and perturbation.

create classmethod

create(
    variables: NDArray[float64],
    perturbed_variables: NDArray[float64],
    perturbed_objectives: NDArray[float64],
    perturbed_constraints: NDArray[float64] | None = None,
    metadata: dict[str, NDArray[Any]] | None = None,
) -> GradientEvaluations

Create a GradientEvaluations object with the given data.

Parameters:

Name	Type	Description	Default
variables	NDArray[float64]	The unperturbed variable vector.	required
perturbed_variables	NDArray[float64]	Perturbed variable values for each realization and perturbation.	required
perturbed_objectives	NDArray[float64]	Objective function values for each realization and perturbation.	required
perturbed_constraints	NDArray[float64] | None	Constraint function values for each realization and perturbation.	None
metadata	dict[str, NDArray[Any]] | None	Optional info for each evaluation.	None

Returns:

Type	Description
GradientEvaluations	A new GradientEvaluations object.

ropt.results.Realizations dataclass

Bases: ResultField

Per-realization activity, success, and weight information.

See Working with Results for usage details.

Result descriptions

Evaluated RealizationsObjective WeightsConstraint Weights

evaluated_realizations: A boolean array indicating which realizations were evaluated. True indicates that a realization was evaluated:

• Shape \((n_r,)\), where:
  • \(n_r\) is the number of realizations.
• Axis type:
  • AxisName.REALIZATION

objective_weights: A two-dimensional array of weights used for each objective in each realization:

• Shape \((n_o, n_r)\), where:
  • \(n_o\) is the number of objectives.
  • \(n_r\) is the number of realizations.
• Axis types:
  • AxisName.OBJECTIVE
  • AxisName.REALIZATION

These weights may change during optimization, depending on the type of objective calculation.

constraint_weights: A two-dimensional array of weights used for each constraint in each realization:

• Shape \((n_c, n_r)\), where:
  • \(n_c\) is the number of constraints.
  • \(n_r\) is the number of realizations.
• Axis types:
  • AxisName.NONLINEAR_CONSTRAINT
  • AxisName.REALIZATION

These weights may change during optimization, depending on the type of constraint calculation.

Attributes:

Name	Type	Description
evaluated_realizations	NDArray[bool_]	Boolean array indicating evaluated realizations.
objective_weights	NDArray[float64] | None	Weights for each objective in each realization, if available.
constraint_weights	NDArray[float64] | None	Weights for each constraint in each realization, if available.

ropt.results.ConstraintInfo dataclass

Bases: ResultField

Constraint differences and violations.

Stores the difference between variable/constraint values and their bounds, and the magnitude of any violations.

• Lower bounds: a negative difference means the value is below the bound (violated).
• Upper bounds: a positive difference means the value is above the bound (violated).
• Violations: the absolute value of the difference when a bound is violated, zero otherwise.

See Working with Results for usage details.

Result descriptions

The class stores the following information for bound, linear constraint, and non-linear constraint differences and violations as one-dimensional vectors:

Bound ConstraintsLinear ConstraintsNonlinear Constraints

• Differences: bound_lower and bound_upper
• Violations: bound_violation
• Shape: \((n_v,)\), where:
  • \(n_v\) is the number of variables.
• Axis type:
  • AxisName.VARIABLE

• Differences: linear_lower and linear_upper
• Violations: linear_violation
• Shape: \((n_l,)\), where:
  • \(n_l\) is the number of linear constraints.
• Axis type:
  • AxisName.LINEAR_CONSTRAINT

• Differences: nonlinear_lower and nonlinear_upper
• Violations: nonlinear_violation
• Shape: \((n_c,)\), where:
  • \(n_c\) is the number of non-linear constraints.
• Axis type:
  • AxisName.NONLINEAR_CONSTRAINT

Attributes:

Name	Type	Description
bound_lower	NDArray[float64] | None	Difference between variables and their lower bounds.
bound_upper	NDArray[float64] | None	Difference between variables and their upper bounds.
linear_lower	NDArray[float64] | None	Difference between linear constraints and their lower bounds.
linear_upper	NDArray[float64] | None	Difference between linear constraints and their upper bounds.
nonlinear_lower	NDArray[float64] | None	Difference between nonlinear constraints and their lower bounds.
nonlinear_upper	NDArray[float64] | None	Difference between nonlinear constraints and their upper bounds.
bound_violation	NDArray[float64] | None	Magnitude of the violation of the variable bounds.
linear_violation	NDArray[float64] | None	Magnitude of the violation of the linear constraints.
nonlinear_violation	NDArray[float64] | None	Magnitude of the violation of the nonlinear constraints.

create classmethod

create(
    context: EnOptContext,
    variables: NDArray[float64],
    constraints: NDArray[float64] | None,
) -> ConstraintInfo | None

Create a ConstraintInfo object with constraint difference data.

This calculates differences between variables/constraints and their bounds. Differences for non-linear constraints are optional. All fields default to None and are only populated if bounds are present and finite.

Parameters:

Name	Type	Description	Default
context	EnOptContext	The optimizer context containing bound definitions.	required
variables	NDArray[float64]	Variable values to check against bounds.	required
constraints	NDArray[float64] | None	Non-linear constraint values, if present.	required

Returns:

Type	Description
ConstraintInfo | None	A newly created ConstraintInfo object, or None if no bounds
ConstraintInfo | None	are available.

ropt.results.results_to_dataframe

results_to_dataframe(
    results: Sequence[Results],
    fields: set[str],
    result_type: Literal["functions", "gradients"],
) -> pd.DataFrame

Aggregate multiple results into a single pandas DataFrame.

Concatenates the specified fields from a sequence of FunctionResults or GradientResults objects. Fields are selected using dot notation (e.g., evaluations.variables); nested metadata entries are accessed as evaluations.metadata.key. Multi-dimensional fields are automatically unstacked into tuple-named columns.

See Working with Results for further details and examples.

Parameters:

Name	Type	Description	Default
results	Sequence[Results]	A sequence of Results objects.	required
fields	set[str]	Field names to include (dot notation for nested fields).	required
result_type	Literal['functions', 'gradients']	"functions" or "gradients".	required

Returns:

Type	Description
DataFrame	A DataFrame with one row per result and requested fields as columns.

Raises:

Type	Description
TypeError	If result_type is invalid or results contain unexpected types.