lumix.core.constraints.LXConstraint

class lumix.core.constraints.LXConstraint(name, lhs=None, sense=LXConstraintSense.LE, rhs_value=None, rhs_func=None, model_type=None, index_func=None, _data=None, _session=None, goal_metadata=None)[source]

Constraint Family - represents multiple constraints indexed by data models.

Like LXVariable, an LXConstraint represents a FAMILY of constraints that automatically expands to multiple solver constraints based on data.

Represents: LHS {<=, >=, ==} RHS

Examples:

# Simple single constraint
LXConstraint("total_capacity")
    .expression(LXLinearExpression().add_term(production, 1.0))
    .le()
    .rhs(100)

# Constraint family - one per resource
# Note: In multi-model constraints, the coefficient lambda receives instances from:
#   - p: Product (from the production variable's indexing)
#   - r: Resource (from this constraint's indexing)
# This allows expressing relationships between different data models.
LXConstraint[Resource]("capacity")
    .expression(LXLinearExpression().add_term(production, lambda p, r: p.usage[r.id]))
    .le()
    .rhs(lambda r: r.capacity)
    .from_data(resources)
    .indexed_by(lambda r: r.id)
Parameters:

  • name (str)

  • lhs (Optional[LXLinearExpression[TModel]])

  • sense (LXConstraintSense)

  • rhs_value (Optional[float])

  • rhs_func (Optional[Callable[[TModel], float]])

  • model_type (Optional[Type[TModel]])

  • index_func (Optional[Callable[[TModel], TIndex]])

  • _data (Optional[List[TModel]])

  • _session (Optional[Any])

  • goal_metadata (Optional['LXGoalMetadata'])

__init__(name, lhs=None, sense=LXConstraintSense.LE, rhs_value=None, rhs_func=None, model_type=None, index_func=None, _data=None, _session=None, goal_metadata=None)
Parameters:
Return type:

None

Methods

__init__(name[, lhs, sense, rhs_value, ...])

as_goal(priority[, weight])

Mark this constraint as a goal for goal programming.

eq()

Set as == constraint.

expression(expr)

Set LHS expression.

from_data(data)

Provide data instances directly.

from_model(model[, session])

Bind to model for indexed constraints.

ge()

Set as >= constraint.

get_instances()

Get the data instances for this constraint family.

indexed_by(func)

Create constraint for each model instance.

is_goal()

Check if this constraint is marked as a goal.

le()

Set as <= constraint.

rhs(value)

Set RHS (constant or function).

Attributes

goal_metadata

index_func

lhs

model_type

rhs_func

rhs_value

sense

name

name: str
lhs: Optional[LXLinearExpression[TypeVar(TModel)]] = None
sense: LXConstraintSense = '<='
rhs_value: Optional[float] = None
rhs_func: Optional[Callable[[TypeVar(TModel)], float]] = None
model_type: Optional[Type[TypeVar(TModel)]] = None
index_func: Optional[Callable[[TypeVar(TModel)], TypeVar(TIndex)]] = None
goal_metadata: Optional[LXGoalMetadata] = None
__deepcopy__(memo)[source]

Custom deepcopy that detaches ORM sessions and handles lambda closures.

This method enables what-if analysis on constraints using ORM data sources by: 1. Materializing lazy-loaded ORM data before copying 2. Detaching ORM objects from database sessions 3. Safely copying lambda functions (index_func, rhs_func, etc.) 4. Deep copying constraint expressions and goal metadata

Parameters:

memo – Dictionary for tracking circular references during deepcopy

Returns:

Deep copy of this constraint with all ORM dependencies resolved

Note

After copying, the new constraint will have _session=None and all data stored in _data as detached objects safe for pickling.

__getstate__()[source]

Support for pickle protocol - detach ORM sessions before pickling.

Returns:

Dictionary of instance state safe for pickling

__setstate__(state)[source]

Support for pickle protocol - restore from pickled state.

Parameters:

state – Dictionary of instance state from pickling

expression(expr)[source]

Set LHS expression.

Parameters:

expr (LXLinearExpression[TypeVar(TModel)]) – Linear expression for left-hand side

Return type:

Self

Returns:

Self for chaining

le()[source]

Set as <= constraint.

Return type:

Self

Returns:

Self for chaining

ge()[source]

Set as >= constraint.

Return type:

Self

Returns:

Self for chaining

eq()[source]

Set as == constraint.

Return type:

Self

Returns:

Self for chaining

rhs(value)[source]

Set RHS (constant or function).

Parameters:

value (Union[float, Callable[[TypeVar(TModel)], float]]) – Right-hand side value (constant or function)

Return type:

Self

Returns:

Self for chaining

Examples

.rhs(100) # constant .rhs(lambda resource: resource.capacity) # from model

from_data(data)[source]

Provide data instances directly.

Parameters:

data (List[TypeVar(TModel)]) – List of model instances

Return type:

Self

Returns:

Self for chaining

from_model(model, session=None)[source]

Bind to model for indexed constraints.

Parameters:
Return type:

Self

Returns:

Self for chaining

indexed_by(func)[source]

Create constraint for each model instance.

Parameters:

func (Callable[[TypeVar(TModel)], TypeVar(TIndex)]) – Function to extract index from model

Return type:

Self

Returns:

Self for chaining

Example

.indexed_by(lambda r: r.id)

as_goal(priority, weight=1.0)[source]

Mark this constraint as a goal for goal programming.

Automatically relaxes the constraint by adding deviation variables and includes it in the goal programming objective function.

Constraint types are handled as follows:

  • LE (expr <= rhs): expr + neg_dev - pos_dev == rhs

    • Positive deviation (exceeding target) is undesired

  • GE (expr >= rhs): expr + neg_dev - pos_dev == rhs

    • Negative deviation (falling short) is undesired

  • EQ (expr == rhs): expr + neg_dev - pos_dev == rhs

    • Both deviations are undesired

Parameters:

  • priority (int) – Priority level (1=highest, 2=second, etc.) Priority 0 is reserved for custom objective terms

  • weight (float) – Relative weight within the same priority level (default: 1.0)

Return type:

Self

Returns:

Self for chaining

Example:

# High priority production goal
.as_goal(priority=1, weight=1.0)

# Lower priority overtime limit
.as_goal(priority=2, weight=0.5)

# Custom objective term (maximize profit)
.as_goal(priority=0, weight=1.0)
is_goal()[source]

Check if this constraint is marked as a goal.

Return type:

bool

Returns:

True if this is a goal constraint, False otherwise

get_instances()[source]

Get the data instances for this constraint family.

Return type:

List[TypeVar(TModel)]

Returns:

List of model instances, or empty list if single constraint

Raises:

ValueError – If indexed but no data source configured

__init__(name, lhs=None, sense=LXConstraintSense.LE, rhs_value=None, rhs_func=None, model_type=None, index_func=None, _data=None, _session=None, goal_metadata=None)
Parameters:
Return type:

None