Sos1Constraint#

class Sos1Constraint#

A Special Ordered Set type 1: at most one member may be nonzero.

Members need not be Binary, and a nonzero member need not equal one. All-zero values are allowed, unlike OneHotConstraint. Negative values also count as nonzero when the member’s domain permits them. This structural constraint stores member IDs rather than an explicit Function.

Each variables entry accepts a variable ID, a standalone DecisionVariable, or an AttachedDecisionVariable. These accepted forms are exposed as the VariableIDLike type alias. Only their IDs are stored; duplicate entries identify the same member. The constructor rejects an empty set. The enclosing Instance validates that the referenced variables exist when inserting the constraint.

Construct and evaluate alternative amounts

>>> from ommx import ConstraintKind, Instance, Sos1Constraint, Sos1ConstraintID
>>> instance = Instance.maximize()
>>> amounts = [
...     instance.new_continuous("amount", lower=-10, upper=10, subscripts=[i])
...     for i in range(3)
... ]
>>> instance.objective = sum(amounts)
>>> condition = Sos1Constraint(variables=amounts)
>>> assert condition.variables == [x.id for x in amounts]
>>> attached = instance.add_sos1_constraint(condition)
>>> cid = attached.constraint_id
>>> assert isinstance(cid, Sos1ConstraintID)
>>> assert instance.evaluate({x.id: 0 for x in amounts}).feasible
>>> one = instance.evaluate({amounts[0].id: 7, amounts[1].id: 0, amounts[2].id: 0})
>>> assert one.feasible
>>> assert instance.evaluate(
...     {amounts[0].id: -7, amounts[1].id: 0, amounts[2].id: 0}
... ).feasible
>>> assert not instance.evaluate(
...     {amounts[0].id: 7, amounts[1].id: 1, amounts[2].id: 0}
... ).feasible
>>> rows = one.constraints_df(kind=ConstraintKind.Sos1)
>>> assert list(rows.index) == [cid]
>>> assert rows.loc[cid, "violation"] == 0.0

See evaluate() for numerical evaluation and constraints_df() for violation and activation diagnostics. The constructor creates an independent value; add_sos1_constraint() returns an attached handle. For explicit IDs, use the sos1_constraints mapping of from_components(). Constraint numbers follow the same cross-family uniqueness rule as regular constraints, including removed rows.

Use the structure directly or express it with regular constraints

The PySCIPOpt Adapter can pass SOS1 directly to its backend. When regular constraints are required, convert_sos1_to_constraints() constructs a Big-M formulation under its domain and finite-bound conditions. The original SOS1 is retained for evaluation, and generated constraints record its provenance.

The reverse operation, promote_sos1_big_m(), validates explicit claims that existing regular rows form an SOS1 formulation. Its Reference explains the mathematical correspondence, accepted bounds, batch outcomes, and complete examples. The rows need not have been generated by OMMX.

__copy__() → Sos1Constraint#

__deepcopy__(_memo: Any) → Sos1Constraint#

__new__(*, variables: Sequence[VariableIDLike], name: Optional[str] = None, subscripts: Sequence[int] = [], description: Optional[str] = None, parameters: Mapping[str, str] = {}) → Sos1Constraint#

Create a new SOS1 constraint.

Args:

variables: Variable IDs or decision-variable objects (at most one can be non-zero). Only their IDs are stored; the enclosing host validates that the referenced variables exist when the constraint is inserted.
name / subscripts / description / parameters: Optional context. Drained into the host’s SoA store on insertion.

__repr__() → str#

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

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

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

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

property description: Optional[str]#: 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.

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