InstanceClass#
- class InstanceClass#
A set of exact
Instancerepresentations, used for inspection and as a target forprepare().Membership checks the Instance as it is: it does not convert expressions, prepare a model, or run a solver. An Adapter’s
INPUT_CLASSis one use of this common representation contract.Clauses describe alternatives
An InstanceClass is a finite union of
InstanceClassClausevalues. An Instance belongs to the class if it satisfies every condition in at least one clause. Conditions from different clauses are not combined. For example, a union of continuous quadratic problems and mixed-integer linear problems does not automatically include mixed-integer quadratic problems. An empty list of clauses accepts no Instance.A clause specifies the allowed kinds of active variables, the objective’s polynomial representation and degree, the relations and polynomial requirements of regular constraints and Indicator bodies, whether active OneHot and SOS1 constraints are allowed, and the optimization direction. Its label identifies it in diagnostics without changing membership.
Inspect membership without changing the model
This target accepts Binary variables, a linear objective, regular linear equalities, and maximization. It does not accept active special constraints.
>>> from ommx import ( ... Equality, ... Instance, ... InstanceClass, ... InstanceClassClause, ... Kind, ... OneHotConstraint, ... OneHotConstraintID, ... PolynomialRequirement, ... Sense, ... ) >>> linear = PolynomialRequirement.at_most(1) >>> target = InstanceClass( ... [ ... InstanceClassClause( ... label="binary-linear-equality", ... allowed_variable_kinds={Kind.Binary}, ... objective_polynomial_requirement=linear, ... regular_constraint_polynomial_requirements={Equality.EqualToZero: linear}, ... allowed_senses={Sense.Maximize}, ... ) ... ] ... ) >>> instance = Instance.maximize() >>> xs = [instance.new_binary("x", subscripts=[i]) for i in range(2)] >>> instance.objective = 3 * xs[0] + 2 * xs[1] >>> _ = instance.add_one_hot_constraint(OneHotConstraint(variables=xs)) >>> assert not target.contains(instance) >>> report = target.check_membership(instance) >>> assert not report.is_member >>> assert report.matching_clauses == [] >>> assert report.clause_reports[0].clause_label == "binary-linear-equality" >>> assert report.clause_reports[0].mismatches >>> assert set(instance.constraints) == {OneHotConstraintID(0)}
OneHot means exactly one member is one. Although a linear equality can express that condition for Binary variables, its dedicated representation does not match a clause that permits only regular equalities. The check leaves OneHot unchanged.
prepare()contains a complete example converting this representation and comparing candidate evaluations before and after it.contains()returns a Boolean.check_membership()returns anInstanceClassMembershipReport; itsclause_reportsdescribe each alternative, andmatching_clausesidentifies every matching index and label. EachInstanceClassClauseReportexposes structuredInstanceClassMismatchvalues with the affected positions or IDs.Alternatively, add a clause that accepts the dedicated OneHot representation:
>>> with_one_hot = InstanceClass( ... [ ... InstanceClassClause( ... label="binary-linear-with-one-hot", ... allowed_variable_kinds={Kind.Binary}, ... objective_polynomial_requirement=linear, ... allowed_senses={Sense.Maximize}, ... allows_one_hot=True, ... ) ... ] ... ) >>> combined = target.union(with_one_hot) >>> assert combined.contains(instance) >>> assert combined.check_membership(instance).matching_clauses == [ ... (1, "binary-linear-with-one-hot") ... ] >>> assert not target.contains(instance)
The active representation determines membership
Variable-kind checks use
active_decision_variables: variables referenced by the active objective and active constraints, including special constraints. Fixed, dependent, and irrelevant variables are excluded, as are variables referenced only by inactive constraints, named functions, or the output objective. Inactive constraints do not contribute their relations, degrees, or special-constraint kinds. A lowered Instance can therefore retain the original special constraints for evaluation while matching a class that disallows them as active constraints.The stored
Functionrepresentation matters as well as its mathematical meaning. Polynomial requirements reject composed expressions even when they happen to define a polynomial; seepowi()for an example. Membership establishes representation requirements, not equivalence to a previous model or a guarantee about the solution returned by a backend.QUBO is one Instance class
qubo()accepts Binary polynomial minimization of degree at most two with no active constraints. Linear and constant objectives are included. The model remains an OMMX Instance:>>> qubo = Instance.minimize() >>> a = qubo.new_binary("a") >>> b = qubo.new_binary("b") >>> qubo.objective = a + 2 * a * b + 3 >>> assert InstanceClass.qubo().contains(qubo) >>> coefficients, offset = qubo.as_qubo_format() >>> assert coefficients == {(a.id, a.id): 1.0, (a.id, b.id): 2.0} >>> assert offset == 3.0
as_qubo_format()extracts active-objective coefficients and the constant without Preparation. Those values do not replace the Instance’s reconstruction rules, retained constraints, or output objective.to_qubo()combines Preparation and formatting and changes the Instance in place;prepare()shows the explicit path.Use a concrete Adapter’s
INPUT_CLASSrather than inferring it from a solver name: some samplers accept Binary polynomials beyond degree two. For membership, recommended policies, and the distinction between automatic and explicit Preparation, seeSolverAdapterandSamplerAdapter.Indicator trigger values
InstanceClassClause.allowed_indicator_trigger_valuesspecifies the allowed trigger values independently ofindicator_body_polynomial_requirements. The latter mapsEqualityto polynomial requirements shared by all admitted trigger values. The default trigger set is{1}; an empty trigger set or an empty body map rejects all Indicators. Values other than 0 and 1 are rejected when constructing the clause.>>> from ommx import Equality, InstanceClassClause, Kind, PolynomialRequirement, Sense >>> clause = InstanceClassClause( ... label="linear indicators at either value", ... allowed_variable_kinds={Kind.Binary}, ... allowed_senses={Sense.Minimize}, ... objective_polynomial_requirement=PolynomialRequirement.at_most(1), ... allowed_indicator_trigger_values={0, 1}, ... indicator_body_polynomial_requirements={ ... Equality.EqualToZero: PolynomialRequirement.at_most(1), ... }, ... ) >>> assert clause.allowed_indicator_trigger_values == {0, 1}
An unsupported trigger value produces
InstanceClassMismatch.IndicatorTriggerNotAllowed, withtrigger_valueandallowed_trigger_values. Body-relation and degree requirements are checked independently, so their diagnostics can accompany a trigger-value mismatch. Membership checking does not transform the Instance.- __repr__() str#
- check_membership(instance: Instance) InstanceClassMembershipReport#
Evaluate membership without mutating or preparing
instance.
- contains(instance: Instance) bool#
Return whether
instancebelongs to this class.
- hubo() InstanceClass#
Class of minimization HUBO formulations accepted by
as_hubo_format()after Preparation.Postconditions#
The target accepts unconstrained minimization Binary HUBO formulations and rejects models outside that class.
>>> from ommx import DecisionVariable, Instance, InstanceClass, Sense >>> x = DecisionVariable.binary(0) >>> linear = Instance.from_components( ... decision_variables=[x], objective=x, active_constraints={}, sense=Sense.Minimize ... ) >>> cubic = Instance.from_components( ... decision_variables=[x], objective=x * x * x, active_constraints={}, sense=Sense.Minimize ... ) >>> maximizing = Instance.from_components( ... decision_variables=[x], objective=x, active_constraints={}, sense=Sense.Maximize ... ) >>> continuous = DecisionVariable.continuous(1) >>> non_binary = Instance.from_components( ... decision_variables=[continuous], objective=continuous, active_constraints={}, sense=Sense.Minimize ... ) >>> constrained = Instance.from_components( ... decision_variables=[x], objective=x, active_constraints={0: x == 1}, sense=Sense.Minimize ... ) >>> target = InstanceClass.hubo() >>> assert target.contains(linear) >>> assert target.contains(cubic) >>> assert not target.contains(maximizing) >>> assert not target.contains(non_binary) >>> assert not target.contains(constrained)
- qubo() InstanceClass#
Class of minimization QUBO formulations accepted by
as_qubo_format()after Preparation.Postconditions#
The target accepts unconstrained minimization QUBO formulations and rejects models outside that class.
>>> from ommx import DecisionVariable, Instance, InstanceClass, Sense >>> x = DecisionVariable.binary(0) >>> linear = Instance.from_components( ... decision_variables=[x], objective=x, active_constraints={}, sense=Sense.Minimize ... ) >>> quadratic = Instance.from_components( ... decision_variables=[x], objective=x * x, active_constraints={}, sense=Sense.Minimize ... ) >>> cubic = Instance.from_components( ... decision_variables=[x], objective=x * x * x, active_constraints={}, sense=Sense.Minimize ... ) >>> maximizing = Instance.from_components( ... decision_variables=[x], objective=x, active_constraints={}, sense=Sense.Maximize ... ) >>> continuous = DecisionVariable.continuous(1) >>> non_binary = Instance.from_components( ... decision_variables=[continuous], objective=continuous, active_constraints={}, sense=Sense.Minimize ... ) >>> constrained = Instance.from_components( ... decision_variables=[x], objective=x, active_constraints={0: x == 1}, sense=Sense.Minimize ... ) >>> target = InstanceClass.qubo() >>> assert target.contains(linear) >>> assert target.contains(quadratic) >>> assert not target.contains(cubic) >>> assert not target.contains(maximizing) >>> assert not target.contains(non_binary) >>> assert not target.contains(constrained)
- union(other: InstanceClass) InstanceClass#
Return the finite union of two instance classes.
- property clauses: list[InstanceClassClause]#
Read-only property.