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). |