IndicatorConstraint#

class IndicatorConstraint#

A condition enforced when a controlling Binary variable equals one.

For a Binary variable \(z\), an Indicator requires \(f(x)\leq0\) or \(f(x)=0\) when \(z=1\). At \(z=0\), the Indicator is satisfied regardless of the body’s value; variable domains and other constraints still apply. This is a one-way implication: a satisfied body does not require \(z=1\).

Construct one from a regular constraint with with_indicator(), or pass indicator_variable, function, and equality to this class. The controlling variable accepts a variable ID, a standalone DecisionVariable, or an AttachedDecisionVariable. These accepted forms are exposed as the VariableIDLike type alias. Only its ID is stored. The enclosing Instance validates that the referenced variables exist and that the controlling variable is Binary when inserting it.

Construct and evaluate a conditional limit

The following model limits the amount to five only when the facility is enabled:

>>> from ommx import ConstraintKind, Equality, IndicatorConstraintID, Instance
>>> instance = Instance.maximize()
>>> enabled = instance.new_binary("enabled")
>>> amount = instance.new_continuous("amount", lower=0, upper=10)
>>> instance.objective = amount
>>> condition = (amount <= 5).with_indicator(enabled)
>>> assert condition.indicator_variable_id == enabled.id
>>> assert condition.equality == Equality.LessThanOrEqualToZero
>>> attached = instance.add_indicator_constraint(condition)
>>> cid = attached.constraint_id
>>> assert isinstance(cid, IndicatorConstraintID)
>>> off = instance.evaluate({enabled.id: 0, amount.id: 6})
>>> on = instance.evaluate({enabled.id: 1, amount.id: 5})
>>> violated = instance.evaluate({enabled.id: 1, amount.id: 6})
>>> assert off.feasible and on.feasible and not violated.feasible
>>> assert not off.constraints_df(kind=ConstraintKind.Indicator).loc[
...     cid, "indicator_active"
... ]
>>> assert on.constraints_df(kind=ConstraintKind.Indicator).loc[cid, "indicator_active"]

The indicator_active column distinguishes an inactive condition from an active condition whose body is satisfied. Indicator results do not have a dual variable. See constraints_df() for the precise columns and violation semantics, and evaluate() for numerical tolerances and invalid activation values.

Identity, transformation, and solver use

add_indicator_constraint() returns an attached handle. The constructor above creates an independent value; context changes on it do not edit a constraint already inserted into a host. Alternatively, provide explicit IDs through the indicator_constraints mapping of from_components(). Constraint numbers must be distinct across all active and removed families, as described by Instance.

relax_indicator_constraint() moves a condition out of the active formulation while retaining it for evaluation. restore_indicator_constraint() makes it active again, subject to the current variable dependencies and fixed values.

A backend may receive this structure directly or require regular constraints. For explicit Big-M lowering, use convert_indicator_to_constraint(); its finite-bound and numerical conditions are part of that operation’s contract. The PySCIPOpt Adapter documents native handling and its complete solving examples.

__copy__() → IndicatorConstraint#

__deepcopy__(_memo: Any) → IndicatorConstraint#

__new__(*, indicator_variable: VariableIDLike, function: builtins.int | builtins.float | numpy.integer | numpy.floating | DecisionVariable | AttachedDecisionVariable | Parameter | Linear | Quadratic | Polynomial | Function, equality: Equality, name: Optional[str] = None, subscripts: Sequence[int] = [], description: Optional[str] = None, parameters: Mapping[str, str] = {}) → IndicatorConstraint#

Create a new indicator constraint.

An indicator constraint is: indicator_variable = 1 → f(x) <= 0 (or f(x) = 0).

Args:

indicator_variable: A variable ID or decision-variable object that activates this constraint. Only its ID is stored; the enclosing host requires the referenced variable to be binary when the constraint is inserted.
function: The constraint function
equality: The equality type (EqualToZero or LessThanOrEqualToZero)
name: Optional name for the constraint
subscripts: Optional subscripts for indexing
description: Optional description
parameters: Optional key-value parameters

__repr__() → str#

set_description(description: str) → IndicatorConstraint#: Set the description. Returns self for method chaining (snapshot mutation).

set_name(name: str) → IndicatorConstraint#: Set the name. Returns self for method chaining (snapshot mutation).

set_parameters(parameters: Mapping[str, str]) → IndicatorConstraint#: Replace all parameters. Returns self for method chaining (snapshot mutation).

set_subscripts(subscripts: Sequence[int]) → IndicatorConstraint#: Set the subscripts. Returns self for method chaining (snapshot mutation).

property description: Optional[str]#: Read-only property.

property equality: Equality#: Read-only property.

property function: Function #: Read-only property.

property indicator_variable_id: int#: Read-only property.

property name: Optional[str]#: Read-only property.

property parameters: dict[str, str]#: Read-only property.

property subscripts: list[int]#: Read-only property.