change exclusive to exactly1

Author: hdavid16

README.md

@@ -107,7 +107,7 @@ Disjunctions can be nested by passing an additional `Disjunct` tag. The Logical
 
 Empty disjuncts are supported in GDP models. When used, the only constraints enforced on the model when the empty disjunct is selected are the global constraints and any other disjunction constraints defined.
 
-For convenience, the `Exactly(1)` selector constraint is added by default when adding a disjunction to the model. In other words, `@disjunction(model, Y)` will add the disjunction and automatically add the logical constraint `Y in Exactly(1)`. For nested disjunctions, the appropriate `Exactly` constraint is added (e.g., `@constraint(model, Y[1:2] in Exactly(Y[3]))`) to indicate that `Exactly 1` logical variable in `Y[1:2]` is set to `true` when `Y[3]` is `true`, and both variables in `Y[1:2]` are set to `false` when `Y[3]` is `false`, meaning the parent disjunct is not selected. Adding the `Exactly` selector constraint by default can be disabled by setting the keyword argument `exclusive` to `false` in the `@disjunction` macro.
+For convenience, the `Exactly(1)` selector constraint is added by default when adding a disjunction to the model. In other words, `@disjunction(model, Y)` will add the disjunction and automatically add the logical constraint `Y in Exactly(1)`. For nested disjunctions, the appropriate `Exactly` constraint is added (e.g., `@constraint(model, Y[1:2] in Exactly(Y[3]))`) to indicate that `Exactly 1` logical variable in `Y[1:2]` is set to `true` when `Y[3]` is `true`, and both variables in `Y[1:2]` are set to `false` when `Y[3]` is `false`, meaning the parent disjunct is not selected. Adding the `Exactly` selector constraint by default can be disabled by setting the keyword argument `exactly1` to `false` in the `@disjunction` macro.
 
 ## MIP Reformulations
 

docs/src/index.md

@@ -107,7 +107,7 @@ Disjunctions can be nested by passing an additional `Disjunct` tag. The Logical
 
 Empty disjuncts are supported in GDP models. When used, the only constraints enforced on the model when the empty disjunct is selected are the global constraints and any other disjunction constraints defined.
 
-For convenience, the `Exactly(1)` selector constraint is added by default when adding a disjunction to the model. In other words, `@disjunction(model, Y)` will add the disjunction and automatically add the logical constraint `Y in Exactly(1)`. For nested disjunctions, the appropriate `Exactly` constraint is added (e.g., `@constraint(model, Y[1:2] in Exactly(Y[3]))`) to indicate that `Exactly 1` logical variable in `Y[1:2]` is set to `true` when `Y[3]` is `true`, and both variables in `Y[1:2]` are set to `false` when `Y[3]` is `false`, meaning the parent disjunct is not selected. Adding the `Exactly` selector constraint by default can be disabled by setting the keyword argument `exclusive` to `false` in the `@disjunction` macro.
+For convenience, the `Exactly(1)` selector constraint is added by default when adding a disjunction to the model. In other words, `@disjunction(model, Y)` will add the disjunction and automatically add the logical constraint `Y in Exactly(1)`. For nested disjunctions, the appropriate `Exactly` constraint is added (e.g., `@constraint(model, Y[1:2] in Exactly(Y[3]))`) to indicate that `Exactly 1` logical variable in `Y[1:2]` is set to `true` when `Y[3]` is `true`, and both variables in `Y[1:2]` are set to `false` when `Y[3]` is `false`, meaning the parent disjunct is not selected. Adding the `Exactly` selector constraint by default can be disabled by setting the keyword argument `exactly1` to `false` in the `@disjunction` macro.
 
 ## MIP Reformulations
 

src/constraints.jl

@@ -117,10 +117,10 @@ function JuMP.delete(model::Model, cref::DisjunctionRef)
         delete!(gdp_data(model).constraint_to_indicator, cref)
     end
     delete!(_disjunctions(model), index(cref))
-    exclusive_dict = gdp_data(model).exclusive_constraints
-    if haskey(exclusive_dict, cref)
-        JuMP.delete(model, exclusive_dict[cref])
-        delete!(exclusive_dict, cref)
+    exactly1_dict = gdp_data(model).exactly1_constraints
+    if haskey(exactly1_dict, cref)
+        JuMP.delete(model, exactly1_dict[cref])
+        delete!(exactly1_dict, cref)
     end
     _set_ready_to_optimize(model, false)
     return 
@@ -316,7 +316,7 @@ function _disjunction(
     model::Model, # TODO: generalize to AbstractModel
     structure::AbstractVector, #generalize for containers
     name::String;
-    exclusive::Bool = true,
+    exactly1::Bool = true,
     extra_kwargs...
 )
     # check for unneeded keywords
@@ -326,12 +326,12 @@ function _disjunction(
     # create the disjunction
     dref = _create_disjunction(_error, model, structure, name, false)
     # add the exactly one constraint if desired
-    if exclusive
+    if exactly1
         lvars = JuMP.constraint_object(dref).indicators
         func = Union{Number, LogicalVariableRef}[1, lvars...]
         set = _MOIExactly(length(lvars) + 1)
         cref = JuMP.add_constraint(model, JuMP.VectorConstraint(func, set))
-        gdp_data(model).exclusive_constraints[dref] = cref
+        gdp_data(model).exactly1_constraints[dref] = cref
     end
     return dref
 end
@@ -354,7 +354,7 @@ function _disjunction(
     structure,
     name::String,
     tag::Disjunct;
-    exclusive::Bool = true,
+    exactly1::Bool = true,
     extra_kwargs...
 )
     # check for unneeded keywords
@@ -366,12 +366,12 @@ function _disjunction(
     obj = constraint_object(dref)
     _add_indicator_var(_DisjunctConstraint(obj, tag.indicator), dref, model)
     # add the exactly one constraint if desired
-    if exclusive
+    if exactly1
         lvars = JuMP.constraint_object(dref).indicators
         func = LogicalVariableRef[tag.indicator, lvars...]
         set = _MOIExactly(length(lvars) + 1)
         cref = JuMP.add_constraint(model, JuMP.VectorConstraint(func, set))
-        gdp_data(model).exclusive_constraints[dref] = cref
+        gdp_data(model).exactly1_constraints[dref] = cref
     end
     return dref
 end
@@ -396,15 +396,15 @@ end
         disjunct_indicators::Vector{LogicalVariableRef},
         [nested_tag::Disjunct],
         [name::String = ""];
-        [exclusive::Bool = true]
+        [exactly1::Bool = true]
     )
 
 Create a disjunction comprised of disjuncts with indicator variables `disjunct_indicators` 
 and add it to `model`. For nested disjunctions, the `nested_tag` is required to indicate 
-which disjunct it will be part of in the parent disjunction. By default, `exclusive` adds 
+which disjunct it will be part of in the parent disjunction. By default, `exactly1` adds 
 a constraint of the form `@constraint(model, disjunct_indicators in Exactly(1))` only 
 allowing one of the disjuncts to be selected; this is required for certain reformulations like 
-[`Hull`](@ref). For nested disjunctions, `exclusive` creates a constraint of the form
+[`Hull`](@ref). For nested disjunctions, `exactly1` creates a constraint of the form
 `@constraint(model, disjunct_indicators in Exactly(nested_tag.indicator))`. 
 To conveniently generate many disjunctions at once, see [`@disjunction`](@ref) 
 and [`@disjunctions`](@ref).

src/datatypes.jl

@@ -391,7 +391,7 @@ mutable struct GDPData
     disjunctions::_MOIUC.CleverDict{DisjunctionIndex, ConstraintData{Disjunction}}
 
     # Exactly one constraint mappings
-    exclusive_constraints::Dict{DisjunctionRef, LogicalConstraintRef}
+    exactly1_constraints::Dict{DisjunctionRef, LogicalConstraintRef}
 
     # Indicator variable mappings
     indicator_to_binary::Dict{LogicalVariableRef, VariableRef}

src/hull.jl

@@ -149,7 +149,7 @@ end
 ################################################################################
 #                              HULL REFORMULATION
 ################################################################################
-requires_exclusive(::Hull) = true
+requires_exactly1(::Hull) = true
 
 function _reformulate_disjunctions(model::Model, method::Hull)
     _query_variable_bounds(model, method)

src/macros.jl

@@ -155,7 +155,7 @@ The recognized keyword arguments in `kw_args` are the following:
     the constraint names are set to `base_name[...]` for each index `...` 
         of the axes `axes`.
 -  `container`: Specify the container type.
--  `exclusive`: Specify a `Bool` whether a constraint should be added to 
+-  `exactly1`: Specify a `Bool` whether a constraint should be added to 
    only allow selecting one disjunct in the disjunction.
 
 To create disjunctions without macros, see [`disjunction`](@ref).

src/model.jl

@@ -54,12 +54,14 @@ _logical_variables(model::Model) = gdp_data(model).logical_variables
 _logical_constraints(model::Model) = gdp_data(model).logical_constraints
 _disjunct_constraints(model::Model) = gdp_data(model).disjunct_constraints
 _disjunctions(model::Model) = gdp_data(model).disjunctions
+_exactly1_constraints(model::Model) = gdp_data(model).exactly1_constraints
 _indicator_to_binary(model::Model) = gdp_data(model).indicator_to_binary
 _indicator_to_constraints(model::Model) = gdp_data(model).indicator_to_constraints
+_constraint_to_indicator(model::Model) = gdp_data(model).constraint_to_indicator
 _reformulation_variables(model::Model) = gdp_data(model).reformulation_variables
 _reformulation_constraints(model::Model) = gdp_data(model).reformulation_constraints
-_ready_to_optimize(model::Model) = gdp_data(model).ready_to_optimize # Determine if the model is ready to call `optimize!` without a optimize hook
 _solution_method(model::Model) = gdp_data(model).solution_method # Get the current solution method
+_ready_to_optimize(model::Model) = gdp_data(model).ready_to_optimize # Determine if the model is ready to call `optimize!` without a optimize hook
 
 # Update the ready_to_optimize field
 function _set_ready_to_optimize(model::Model, is_ready::Bool)

src/reformulate.jl

@@ -47,22 +47,22 @@ end
 #                              DISJUNCTIONS
 ################################################################################
 """
-    requires_exclusive(method::AbstractReformulationMethod)
+    requires_exactly1(method::AbstractReformulationMethod)
 
 Return a `Bool` whether `method` requires that `Exactly 1` disjunct be selected 
 as true for each disjunction. For new reformulation method types, this should be 
 extended to return `true` if such a constraint is required (defaults to `false` otherwise).
 """
-requires_exclusive(::AbstractReformulationMethod) = false
+requires_exactly1(::AbstractReformulationMethod) = false
 
 # disjunctions
 function _reformulate_all_disjunctions(model::Model, method::AbstractReformulationMethod)
     for (idx, disj) in _disjunctions(model)
         disj.constraint.nested && continue #only reformulate top level disjunctions
         dref = DisjunctionRef(model, idx)
-        if requires_exclusive(method) && !haskey(gdp_data(model).exclusive_constraints, dref)
-            error("Reformulation method `$method` requires exclusive disjuncts for " *
-                  "disjunctions, but `exclusive = false` for disjunction `$dref`.")
+        if requires_exactly1(method) && !haskey(gdp_data(model).exactly1_constraints, dref)
+            error("Reformulation method `$method` requires disjunctions where only 1 disjunct is selected, " *
+                  "but `exactly1 = false` for disjunction `$dref`.")
         end
         ref_cons = reformulate_disjunction(model, disj.constraint, method)
         for (i, ref_con) in enumerate(ref_cons)

test/constraints/bigm.jl

@@ -288,10 +288,10 @@ function test_nested_bigm()
     @variable(model, z[1:2], Logical)
     @constraint(model, x <= 5, Disjunct(y[1]))
     @constraint(model, x >= 5, Disjunct(y[2]))
-    @disjunction(model, inner, y, Disjunct(z[1]), exclusive = false)
+    @disjunction(model, inner, y, Disjunct(z[1]), exactly1 = false)
     @constraint(model, x <= 10, Disjunct(z[1]))
     @constraint(model, x >= 10, Disjunct(z[2]))
-    @disjunction(model, outer, z, exclusive = false)
+    @disjunction(model, outer, z, exactly1 = false)
 
     reformulate_model(model, BigM())
     bvrefs = DP._indicator_to_binary(model)

test/constraints/disjunction.jl

@@ -51,7 +51,7 @@ function test_disjunction_add_success()
     disj = DisjunctionRef(model, DisjunctionIndex(1))
     disj2 = DisjunctionRef(model, DisjunctionIndex(2))
     @test @disjunction(model, y) == disj
-    @test @disjunction(model, disj2, y, exclusive = false) == disj2
+    @test @disjunction(model, disj2, y, exactly1 = false) == disj2
     @test owner_model(disj) == model
     @test is_valid(model, disj)
     @test index(disj) == DisjunctionIndex(1)
@@ -62,8 +62,8 @@ function test_disjunction_add_success()
     @test DP._disjunctions(model)[index(disj)] == DP._constraint_data(disj)
     @test !constraint_object(disj).nested
     @test constraint_object(disj).indicators == y
-    @test haskey(gdp_data(model).exclusive_constraints, disj)
-    @test !haskey(gdp_data(model).exclusive_constraints, disj2)
+    @test haskey(gdp_data(model).exactly1_constraints, disj)
+    @test !haskey(gdp_data(model).exactly1_constraints, disj2)
     @test disj == copy(disj)
 end
 
@@ -89,7 +89,7 @@ function test_disjunction_add_nested()
     @test !constraint_object(outer).nested
     @test haskey(DP._indicator_to_constraints(model), z[1])
     @test inner in DP._indicator_to_constraints(model)[z[1]]
-    @test haskey(gdp_data(model).exclusive_constraints, inner)
+    @test haskey(gdp_data(model).exactly1_constraints, inner)
 end
 
 function test_disjunction_add_array()
@@ -189,15 +189,15 @@ function test_disjunction_delete()
     @test delete(model, disj) isa Nothing
     @test !haskey(gdp_data(model).disjunctions, index(disj))
     @test !DP._ready_to_optimize(model)
-    @test !haskey(gdp_data(model).exclusive_constraints, disj)
+    @test !haskey(gdp_data(model).exactly1_constraints, disj)
 
     model = GDPModel()
     @variable(model, x)
     @variable(model, y[1:2], Logical)
     @variable(model, z[1:2], Logical)
     @constraint(model, x <= 5, Disjunct(y[1]))
     @constraint(model, x >= 5, Disjunct(y[2]))
-    @disjunction(model, inner, y, Disjunct(z[1]), exclusive = false)
+    @disjunction(model, inner, y, Disjunct(z[1]), exactly1 = false)
 
     @test delete(model, inner) isa Nothing
     @test !haskey(gdp_data(model).disjunctions, index(inner))
@@ -219,7 +219,7 @@ function test_disjunction_function()
     set_name(disj, "new_name")
     @test name(disj) == "new_name"
     @test haskey(DP._disjunctions(model), index(disj))
-    @test haskey(gdp_data(model).exclusive_constraints, disj)
+    @test haskey(gdp_data(model).exactly1_constraints, disj)
 end
 
 function test_disjunction_function_nested()
@@ -233,7 +233,7 @@ function test_disjunction_function_nested()
     @constraint(model, x >= 10, Disjunct(z[2]))
     disj1 = DisjunctionRef(model, DisjunctionIndex(1))
     disj2 = DisjunctionRef(model, DisjunctionIndex(2))
-    @test disjunction(model, y, Disjunct(z[1]), "inner", exclusive = false) == disj1
+    @test disjunction(model, y, Disjunct(z[1]), "inner", exactly1 = false) == disj1
     @test disjunction(model, z, "outer") == disj2
 
     @test is_valid(model, disj1)
@@ -244,7 +244,7 @@ function test_disjunction_function_nested()
     @test !constraint_object(disj2).nested
     @test haskey(DP._indicator_to_constraints(model), z[1])
     @test disj1 in DP._indicator_to_constraints(model)[z[1]]
-    @test !haskey(gdp_data(model).exclusive_constraints, disj1)
+    @test !haskey(gdp_data(model).exactly1_constraints, disj1)
 end
 
 @testset "Disjunction" begin