Problem Definition¶
Declarative, immutable problem specification consumed by all layers.
ProblemDefinition¶
surrox.ProblemDefinition
¶
Bases: BaseModel
Immutable, declarative definition of an optimization problem.
Central object consumed by all layers of the surrox pipeline. Validated exhaustively at construction time, including cross-field consistency checks.
Attributes:
| Name | Type | Description |
|---|---|---|
variables |
tuple[Variable, ...]
|
Variables with their types, roles, and bounds. |
objectives |
tuple[Objective, ...]
|
Optimization objectives (at least one required). |
linear_constraints |
tuple[LinearConstraint, ...]
|
Analytical linear constraints on decision variables. |
data_constraints |
tuple[DataConstraint, ...]
|
Surrogate-based constraints on predicted columns. |
monotonic_relations |
tuple[MonotonicRelation, ...]
|
Known monotonic relationships for surrogate training. |
scenarios |
tuple[Scenario, ...]
|
Named context variable assignments for scenario comparison. |
Variables¶
surrox.Variable
¶
surrox.ContinuousBounds
¶
Bases: BaseModel
Bounds for a continuous variable, defined by a lower and upper limit.
Attributes:
| Name | Type | Description |
|---|---|---|
lower |
float
|
Minimum allowed value (exclusive of upper). |
upper |
float
|
Maximum allowed value. |
surrox.IntegerBounds
¶
Bases: BaseModel
Bounds for an integer variable, defined by a lower and upper limit.
Attributes:
| Name | Type | Description |
|---|---|---|
lower |
int
|
Minimum allowed value (exclusive of upper). |
upper |
int
|
Maximum allowed value. |
surrox.CategoricalBounds
¶
Bases: BaseModel
Bounds for a categorical variable, defined by a set of unordered categories.
Attributes:
| Name | Type | Description |
|---|---|---|
categories |
tuple[str, ...]
|
Allowed category values. Must contain at least 2 unique entries. |
surrox.OrdinalBounds
¶
Bases: BaseModel
Bounds for an ordinal variable, defined by an ordered sequence of categories.
Attributes:
| Name | Type | Description |
|---|---|---|
categories |
tuple[str, ...]
|
Allowed category values in order. Must contain at least 2 unique entries. |
Objectives¶
surrox.Objective
¶
Bases: BaseModel
An optimization objective targeting a dataset column.
Attributes:
| Name | Type | Description |
|---|---|---|
name |
str
|
Unique name for this objective. |
direction |
Direction
|
Whether to minimize or maximize. |
column |
str
|
Dataset column that the surrogate predicts. |
reference_value |
float | None
|
Optional baseline value for comparison. |
Constraints¶
surrox.LinearConstraint
¶
Bases: BaseModel
An analytical linear constraint on decision variables.
Enforces sum(coeff_i * x_i) operator rhs where coefficients map
decision variable names to their weights.
Attributes:
| Name | Type | Description |
|---|---|---|
name |
str
|
Unique name for this constraint. |
coefficients |
dict[str, float]
|
Mapping of decision variable names to their coefficients. Must be non-empty with no zero values. |
operator |
ConstraintOperator
|
Comparison operator (le, ge, eq). |
rhs |
float
|
Right-hand side value. |
severity |
ConstraintSeverity
|
Hard constraints must be satisfied; soft constraints are penalized. |
penalty_weight |
float | None
|
Required (and positive) for soft constraints, must be None for hard. |
surrox.DataConstraint
¶
Bases: BaseModel
A surrogate-based constraint evaluated on a predicted dataset column.
Enforces prediction(column) operator limit. A surrogate model is trained
for the target column, and the constraint is evaluated on its predictions.
Attributes:
| Name | Type | Description |
|---|---|---|
name |
str
|
Unique name for this constraint. |
column |
str
|
Dataset column that the surrogate predicts. |
operator |
ConstraintOperator
|
Comparison operator (le, ge, eq). |
limit |
float
|
Threshold value. |
tolerance |
float | None
|
Required (and positive) for eq operator, must be None otherwise. |
severity |
ConstraintSeverity
|
Hard constraints must be satisfied; soft constraints are penalized. |
penalty_weight |
float | None
|
Required (and positive) for soft constraints, must be None for hard. |
Domain Knowledge¶
surrox.MonotonicRelation
¶
Bases: BaseModel
A known monotonic relationship between a decision variable and a target.
Encodes domain knowledge that increasing a decision variable always increases (or decreases) a specific objective or data constraint prediction. Used to constrain surrogate model training.
Attributes:
| Name | Type | Description |
|---|---|---|
decision_variable |
str
|
Name of the numeric decision variable. |
objective_or_constraint |
str
|
Name of the objective or data constraint. |
direction |
MonotonicDirection
|
Whether the relationship is increasing or decreasing. |
Scenarios¶
surrox.Scenario
¶
Bases: BaseModel
A named set of fixed context variable values for scenario-based optimization.
Scenarios fix context variables to specific values, enabling what-if comparisons across different operating conditions.
Attributes:
| Name | Type | Description |
|---|---|---|
name |
str
|
Unique name for this scenario. |
context_values |
dict[str, Any]
|
Mapping of context variable names to their fixed values. Must contain at least one entry. |
Dataset¶
surrox.BoundDataset
¶
Bases: BaseModel
A DataFrame validated against a ProblemDefinition.
Validates at construction that all required columns exist, contain no missing values, and satisfy dtype and bounds constraints.
Attributes:
| Name | Type | Description |
|---|---|---|
problem |
ProblemDefinition
|
The problem definition to validate against. |
dataframe |
DataFrame
|
Historical data. Columns must match variable names and target columns. |
Types¶
surrox.DType
¶
Bases: StrEnum
Data type of a variable.
surrox.Role
¶
Bases: StrEnum
Role of a variable in the optimization problem.
surrox.Direction
¶
Bases: StrEnum
Optimization direction for an objective.
surrox.ConstraintOperator
¶
Bases: StrEnum
Comparison operator for constraints.
surrox.MonotonicDirection
¶
Bases: StrEnum
Direction of a monotonic relationship between a variable and a target.