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, scaling, and pandas/polars export.

ropt.results.Results `dataclass`

Bases: AxisMetadata, 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 axis name to label tuples for DataFrame export. Keys are `AxisName` values, or the name of a metadata key that defines a user axis.

to_pandas

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

Export selected fields to a pandas DataFrame.

Fields are named by a dotted path from this result, such as "functions.objectives", "scaled.variables" or "target_objective". A path may end in one or more mapping keys, as "metadata.run.id" does. Each selected path becomes a column of that name.

Multi-dimensional 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 (path, label, ...).

Paths whose value is None, and missing mapping keys, are skipped. A path that does not name a value raises a ValueError.

See Working with Results for further details and examples.

Parameters:

Name	Type	Description	Default
`select`	`Iterable[str]`	The dotted paths of the fields to export.	required
`unstack`	`Iterable[str] \| None`	Axes to pivot into columns (default: none).	`None`

Returns:

Type	Description
`DataFrame`	A DataFrame with the selected fields as columns.

Raises:

Type	Description
`UnsupportedError`	If the `pandas` module is not installed.

to_polars

to_polars(
    select: Iterable[str],
    unstack: Iterable[str] | None = None,
    sep: str = ",",
) -> pl.DataFrame

Export selected fields to a polars DataFrame.

This is the polars counterpart of to_pandas, returned in long format with tuple column names joined into a single string using sep. See Exporting to polars for details.

Parameters:

Name	Type	Description	Default
`select`	`Iterable[str]`	The dotted paths of the fields to export.	required
`unstack`	`Iterable[str] \| None`	Axes to pivot into columns (default: none).	`None`
`sep`	`str`	Separator used to join unstacked column names.	`','`

Returns:

Type	Description
`DataFrame`	A DataFrame with axis labels and the selected fields as columns.

Raises:

Type	Description
`UnsupportedError`	If the `polars` module is not installed.

ropt.results.AxisMetadata

Mixin for dataclasses whose fields carry axis metadata.

get_axes `classmethod`

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

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[str, ...]`	A tuple of axis names, each an `AxisName` value.

Raises:

Type	Description
`ValueError`	If the field name is not recognized.

ropt.results.ResultField `dataclass`

Bases: AxisMetadata

Base class for result field containers that carry axis metadata.

See Working with Results for how axis metadata is used.

ropt.results.FunctionResults `dataclass`

Bases: Results

Results of a function evaluation batch.

Fields that have two domains appear twice: once here, in the domain that was configured, and once under scaled, in the domain the optimizer works in. The target_objective is the exception. It is a weighted total over objectives that may differ in both scale and direction, so it exists only in the optimizer's domain and has no scaled counterpart.

See Working with Results for usage details.

Attributes:

Name	Type	Description
`variables`	`NDArray[float64]`	The variable vector that was evaluated.
`evaluations`	`FunctionEvaluations`	Per-realization values returned by the evaluator.
`realizations`	`Realizations`	Realization activity and weights.
`functions`	`Functions \| None`	Aggregated function values, or `None` if all failed.
`target_objective`	`NDArray[float64] \| None`	The value the optimizer minimizes, in its own domain.
`scaled`	`ScaledFunctionResults`	The same quantities as the optimizer works with them.
`constraint_info`	`ConstraintInfo \| None`	Constraint differences and violations, if applicable.

ropt.results.ScaledFunctionResults `dataclass`

Bases: ResultField

The scaled counterpart of the fields that have two domains.

Each field mirrors the field of the same name on FunctionResults, expressed in the domain the optimizer works in.

Attributes:

Name	Type	Description
`variables`	`NDArray[float64]`	The variable vector the optimizer proposed.
`functions`	`Functions \| None`	Scaled aggregates, or `None` if all realizations failed.
`constraint_info`	`ConstraintInfo \| None`	Constraint differences in the optimizer's domain.

ropt.results.GradientResults `dataclass`

Bases: Results

Results of a gradient evaluation batch.

Fields that have two domains appear twice: once here, in the domain that was configured, and once under scaled, in the domain the optimizer works in. The target_gradient is the exception. It differentiates a weighted total over objectives that may differ in both scale and direction, with respect to the scaled variables, so it exists only in the optimizer's domain and has no scaled counterpart.

See Working with Results for usage details.

Attributes:

Name	Type	Description
`variables`	`NDArray[float64]`	The variable vector that was perturbed.
`perturbed_variables`	`NDArray[float64]`	The perturbed vectors that were evaluated.
`evaluations`	`GradientEvaluations`	Per-perturbation values returned by the evaluator.
`realizations`	`Realizations`	Realization activity and weights.
`gradients`	`Gradients \| None`	Aggregated gradients, or `None` if estimation failed.
`target_gradient`	`NDArray[float64] \| None`	The gradient the optimizer descends, in its own domain.
`scaled`	`ScaledGradientResults`	The same quantities as the optimizer works with them.

ropt.results.ScaledGradientResults `dataclass`

Bases: ResultField

The scaled counterpart of the fields that have two domains.

Each field mirrors the field of the same name on GradientResults, expressed in the domain the optimizer works in.

Attributes:

Name	Type	Description
`variables`	`NDArray[float64]`	The variable vector the optimizer proposed.
`perturbed_variables`	`NDArray[float64]`	The perturbed vectors in the optimizer's domain.
`gradients`	`Gradients \| None`	Scaled gradients, or `None` if estimation failed.

ropt.results.Functions `dataclass`

Bases: ResultField

Aggregated objective and constraint function values.

The same class carries both domains: the values the optimizer works with are found under scaled, the values as configured directly on the result.

See Working with Results for usage details.

There is no target objective here: the quantity the optimizer minimizes is a weighted total over objectives that may differ in both scale and direction, so it has no counterpart in the configured domain. It is reported as target_objective on FunctionResults.

Result descriptions

ObjectivesConstraints

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
`objectives`	`NDArray[float64]`	The value of each individual objective.
`constraints`	`NDArray[float64] \| None`	The value of each individual constraint, if present.

from_scaled `classmethod`

from_scaled(
    context: EnOptContext, scaled: Functions
) -> Functions

Derive the configured function values from the scaled ones.

Parameters:

Name	Type	Description	Default
`context`	`EnOptContext`	The context of the run.	required
`scaled`	`Functions`	The values as the optimizer sees them.	required

Returns:

Type	Description
`Functions`	A new `Functions` object.

ropt.results.Gradients `dataclass`

Bases: ResultField

Aggregated objective and constraint gradients.

The same class carries both domains: the gradients the optimizer works with are found under scaled, differentiated with respect to the scaled variables, the gradients as configured directly on the result.

See Working with Results for usage details.

There is no target gradient here: the quantity the optimizer descends is a weighted total over objectives that may differ in both scale and direction, so it has no counterpart in the configured domain. It is reported as target_gradient on GradientResults.

Result descriptions

Objective GradientsConstraint Gradients

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
`objectives`	`NDArray[float64]`	The gradient of each individual objective.
`constraints`	`NDArray[float64] \| None`	The gradient of each individual constraint, if present.

from_scaled `classmethod`

from_scaled(
    context: EnOptContext, scaled: Gradients
) -> Gradients

Derive the configured gradients from the scaled ones.

Parameters:

Name	Type	Description	Default
`context`	`EnOptContext`	The context of the run.	required
`scaled`	`Gradients`	The gradients as the optimizer sees them.	required

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

An entry whose values are arrays rather than scalars has shape \((n_r, n_k)\) and carries a second, user-defined axis named after its key. See User-defined axes.

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
`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(
    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
`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:

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:

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:

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

An entry whose values are arrays rather than scalars has shape \((n_r, n_p, n_k)\) and carries a third, user-defined axis named after its key. See User-defined axes.

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
`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(
    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
`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.

from_scaled `classmethod`

from_scaled(
    context: EnOptContext, scaled: ConstraintInfo
) -> ConstraintInfo

Convert constraint differences to the domain the user configured.

Parameters:

Name	Type	Description	Default
`context`	`EnOptContext`	The context used by the source of the results.	required
`scaled`	`ConstraintInfo`	The differences as the optimizer sees them.	required

Returns:

Type	Description
`ConstraintInfo`	The same differences expressed in unscaled units.

ropt.results.results_to_pandas

results_to_pandas(
    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, one row per result. See Aggregating multiple results for field selection and unstacking.

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.
`UnsupportedError`	If the `pandas` module is not installed.

ropt.results.results_to_polars

results_to_polars(
    results: Sequence[Results],
    fields: set[str],
    result_type: Literal["functions", "gradients"],
    sep: str = ",",
) -> pl.DataFrame

Aggregate multiple results into a single polars DataFrame.

This is the polars counterpart of results_to_pandas, returned in long format with tuple column names joined into a single string using sep. Unlike the pandas export, fields with different granularities are aligned into one table rather than kept as separate blocks. See Exporting to polars for details.

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
`sep`	`str`	Separator used to join unstacked column names.	`','`

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.
`UnsupportedError`	If the `polars` module is not installed.

Evaluation Results

ropt.results

ropt.results.Results dataclass

to_pandas

to_polars

ropt.results.AxisMetadata

get_axes classmethod

ropt.results.ResultField dataclass

ropt.results.FunctionResults dataclass

ropt.results.ScaledFunctionResults dataclass

ropt.results.GradientResults dataclass

ropt.results.ScaledGradientResults dataclass

ropt.results.Functions dataclass

from_scaled classmethod

ropt.results.Gradients dataclass

from_scaled classmethod

ropt.results.FunctionEvaluations dataclass

create classmethod

ropt.results.GradientEvaluations dataclass

create classmethod

ropt.results.Realizations dataclass

ropt.results.ConstraintInfo dataclass

create classmethod

from_scaled classmethod

ropt.results.results_to_pandas

ropt.results.results_to_polars

ropt.results.Results `dataclass`

get_axes `classmethod`

ropt.results.ResultField `dataclass`

ropt.results.FunctionResults `dataclass`

ropt.results.ScaledFunctionResults `dataclass`

ropt.results.GradientResults `dataclass`

ropt.results.ScaledGradientResults `dataclass`

ropt.results.Functions `dataclass`

from_scaled `classmethod`

ropt.results.Gradients `dataclass`

from_scaled `classmethod`

ropt.results.FunctionEvaluations `dataclass`

create `classmethod`

ropt.results.GradientEvaluations `dataclass`

create `classmethod`

ropt.results.Realizations `dataclass`

ropt.results.ConstraintInfo `dataclass`

create `classmethod`

from_scaled `classmethod`