Skip to content

Results

Data structures returned by the surrox pipeline.

Top-Level Results

surrox.SurroxResult

Bases: BaseModel

Combined result of a single surrox pipeline run.

Attributes:

Name Type Description
optimization OptimizationResult

Pareto-optimal points and optimization metadata.

analysis AnalysisResult

Summary analysis computed automatically after optimization.

surrox.ScenariosResult

Bases: BaseModel

Combined result of a multi-scenario surrox pipeline run.

Attributes:

Name Type Description
per_scenario dict[str, SurroxResult]

Results keyed by scenario name.

comparison ScenarioComparisonResult

Cross-scenario comparison metrics.

Optimization Results

surrox.OptimizationResult

Bases: BaseModel

Result of the optimization process.

Attributes:

Name Type Description
feasible_points tuple[EvaluatedPoint, ...]

Pareto-optimal points satisfying all hard constraints.

infeasible_points tuple[EvaluatedPoint, ...]

Points that violated at least one hard constraint.

has_feasible_solutions bool

Whether any feasible solutions were found.

compromise_index int | None

Index into feasible_points of the recommended compromise solution (multi-objective only).

hypervolume float | None

Hypervolume indicator of the Pareto front (multi-objective only).

problem ProblemDefinition

The problem definition used for optimization.

n_generations int

Number of generations executed.

n_evaluations int

Total number of candidate evaluations.

surrox.optimizer.result.EvaluatedPoint

Bases: BaseModel

A single evaluated candidate from the optimization.

Attributes:

Name Type Description
variables dict[str, Any]

Decision and context variable values.

objectives dict[str, float]

Predicted objective values by name.

constraints tuple[ConstraintEvaluation, ...]

Constraint evaluations with violation info.

feasible bool

Whether all hard constraints are satisfied.

extrapolation_distance float

Distance to the training data manifold.

is_extrapolating bool

Whether this point is outside the training domain.

surrox.optimizer.result.ConstraintEvaluation

Bases: BaseModel

Evaluation of a single constraint at a candidate point.

Attributes:

Name Type Description
name str

Name of the constraint.

violation float

Constraint violation magnitude (0.0 if satisfied).

prediction float

Predicted value from the surrogate.

severity ConstraintSeverity

Hard or soft constraint.

lower_bound float | None

Lower conformal prediction bound (data constraints only).

upper_bound float | None

Upper conformal prediction bound (data constraints only).

Analysis Results

surrox.AnalysisResult

Bases: BaseModel

Result of the automatic post-optimization analysis.

Attributes:

Name Type Description
summary Summary

High-level summary including solution overview, baseline comparison, constraint status, surrogate quality, and extrapolation warnings.

surrox.analysis.summary.Summary

Bases: BaseModel

Automatic post-optimization summary.

Attributes:

Name Type Description
solution_summary SolutionSummary

Overview of feasible/infeasible solutions and best objectives.

baseline_comparison BaselineComparison | None

Improvement vs. historical best (None if no feasible solutions).

constraint_status tuple[ConstraintStatus, ...]

Status of each constraint at the recommended point.

surrogate_quality tuple[SurrogateQuality, ...]

Quality metrics per trained surrogate.

extrapolation_warnings tuple[ExtrapolationWarning, ...]

Feasible points flagged as extrapolating.

monotonicity_violations tuple[MonotonicityViolation, ...]

Detected violations of declared monotonic relations.

surrox.analysis.summary.SolutionSummary

Bases: BaseModel

High-level overview of the optimization outcome.

Attributes:

Name Type Description
n_feasible int

Number of feasible Pareto-optimal points.

n_infeasible int

Number of infeasible points.

best_objectives dict[str, float]

Best value found per objective across feasible points.

compromise_objectives dict[str, float] | None

Objective values at the compromise point (multi-objective only).

hypervolume float | None

Hypervolume indicator of the Pareto front (multi-objective only).

surrox.analysis.summary.BaselineComparison

Bases: BaseModel

Comparison of the recommended solution against historical data.

Attributes:

Name Type Description
recommended_objectives dict[str, float]

Predicted objectives at the recommended point.

historical_best_per_objective dict[str, float]

Best historical value per objective from the training data.

improvement dict[str, float]

Improvement over historical best (positive = better).

surrox.analysis.summary.ConstraintStatus

Bases: BaseModel

Status of a constraint at the recommended point.

Attributes:

Name Type Description
evaluation ConstraintEvaluation

Raw constraint evaluation with violation and prediction.

status ConstraintStatusKind

Classification as satisfied, active, or violated.

margin float

Distance to the constraint boundary (positive = satisfied).

surrox.analysis.summary.SurrogateQuality

Bases: BaseModel

Quality metrics for a trained surrogate ensemble.

Attributes:

Name Type Description
column str

Target column name.

cv_rmse float

Best cross-validation RMSE from the Optuna study.

conformal_coverage float

Conformal prediction interval coverage level.

ensemble_size int

Number of models in the ensemble.

warning str | None

Quality warning if CV RMSE significantly exceeds conformity scores.

surrox.analysis.summary.ExtrapolationWarning

Bases: BaseModel

Warning for a feasible point that lies outside the training data domain.

Attributes:

Name Type Description
point_index int

Index into the feasible points list.

distance float

k-NN distance to the training data manifold.

surrox.analysis.summary.MonotonicityViolation

Bases: BaseModel

Detected violation of a declared monotonic relationship.

Attributes:

Name Type Description
decision_variable str

Variable involved in the violation.

target str

Objective or constraint target.

declared_direction MonotonicDirection

Expected monotonic direction.

violation_fraction float

Fraction of grid intervals where monotonicity is violated.

max_reversal float

Maximum absolute reversal magnitude.

Detail Analysis Results

surrox.analysis.shap.FeatureImportanceResult

Bases: BaseModel

Mean absolute SHAP-based feature importance for a target column.

Attributes:

Name Type Description
column str

Target column name.

importances dict[str, float]

Mean |SHAP| per feature (all variables).

decision_importances dict[str, float]

Mean |SHAP| per feature (decision variables only).

surrox.analysis.shap.ShapGlobalResult

Bases: BaseModel

Global SHAP explanation over a background dataset.

Attributes:

Name Type Description
column str

Target column name.

feature_names tuple[str, ...]

Feature names in column order.

shap_values NumpyArray

SHAP value matrix, shape (n_samples, n_features).

base_value float

Expected model output (ensemble-weighted).

feature_values NumpyArray

Feature value matrix, shape (n_samples, n_features).

surrox.analysis.shap.ShapLocalResult

Bases: BaseModel

Local SHAP explanation for a single Pareto-optimal point.

Attributes:

Name Type Description
column str

Target column name.

feature_names tuple[str, ...]

Feature names in column order.

shap_values NumpyArray

SHAP values for this point, shape (n_features,).

base_value float

Expected model output (ensemble-weighted).

feature_values dict[str, float]

Feature values at this point.

predicted_value float

Model prediction (base_value + sum of SHAP values).

surrox.analysis.pdp.PDPICEResult

Bases: BaseModel

Partial Dependence Plot and Individual Conditional Expectation curves.

Attributes:

Name Type Description
variable_name str

Decision variable being varied.

column str

Target column being predicted.

grid_values NumpyArray

Grid points along the variable range, shape (n_grid,).

pdp_values NumpyArray

Ensemble-weighted PDP values, shape (n_grid,).

ice_values NumpyArray

Ensemble-weighted ICE curves, shape (n_samples, n_grid).

surrox.analysis.trade_off.TradeOffResult

Bases: BaseModel

Trade-off analysis between objective pairs on the Pareto front.

Attributes:

Name Type Description
objective_pairs tuple[tuple[str, str], ...]

All pairwise combinations of objectives.

marginal_rates MarginalRates

Marginal rates of substitution per objective pair, each an array of rates between adjacent Pareto points.

pareto_objectives NumpyArray

Objective values on the Pareto front, shape (n_points, n_objectives), sorted by first objective.

surrox.analysis.what_if.WhatIfResult

Bases: BaseModel

Result of a what-if prediction for a hypothetical variable setting.

Attributes:

Name Type Description
variables dict[str, Any]

The hypothetical variable values that were evaluated.

objectives dict[str, WhatIfPrediction]

Predictions per objective.

constraints dict[str, WhatIfPrediction]

Predictions per data constraint.

extrapolation_distance float

Distance to the training data manifold.

is_extrapolating bool

Whether this point is outside the training domain.

surrox.analysis.what_if.WhatIfPrediction

Bases: BaseModel

Prediction for a single objective or constraint in a what-if scenario.

Attributes:

Name Type Description
predicted float

Point prediction from the surrogate ensemble.

lower float

Lower conformal prediction interval bound.

upper float

Upper conformal prediction interval bound.

recommended_value float

Prediction at the recommended (compromise) point for comparison.

historical_mean float

Mean of the historical data for this column.

Scenario Comparison

surrox.ScenarioComparisonResult

Bases: BaseModel

Cross-scenario comparison of recommended decision variable settings.

Attributes:

Name Type Description
scenario_names tuple[str, ...]

Names of the compared scenarios.

variable_robustness dict[str, VariableRobustness]

Robustness assessment per decision variable.

surrox.analysis.scenario.VariableRobustness

Bases: BaseModel

Robustness assessment for a single decision variable across scenarios.

Attributes:

Name Type Description
variable_name str

Name of the decision variable.

values_per_scenario dict[str, Any]

Recommended value per scenario.

is_robust bool

Whether the variable is stable across scenarios (spread < 5% of bounds range).

spread float

Absolute range of values across scenarios (0.0 for categorical agreement).