Merge pull request #80 from hdavid16/juliacon_proceedings

Author: hdavid16

Project.toml

@@ -1,7 +1,7 @@
 name = "DisjunctiveProgramming"
 uuid = "0d27d021-0159-4c7d-b4a7-9ccb5d9366cf"
 authors = ["hdavid16 <[email protected]>"]
-version = "0.4.0"
+version = "0.4.1"
 
 [deps]
 JuMP = "4076af6c-e467-56ae-b986-b466b2749572"

README.md

@@ -134,19 +134,28 @@ The example below is from the [Cornell University Computational Optimization Ope
 
 ```julia
 using DisjunctiveProgramming
+using HiGHS
 
-m = GDPModel()
+m = GDPModel(HiGHS.Optimizer)
 @variable(m, 0 ≤ x[1:2] ≤ 20)
 @variable(m, Y[1:2], Logical)
 @constraint(m, [i = 1:2], [2,5][i] ≤ x[i] ≤ [6,9][i], DisjunctConstraint(Y[1]))
 @constraint(m, [i = 1:2], [8,10][i] ≤ x[i] ≤ [11,15][i], DisjunctConstraint(Y[2]))
 @disjunction(m, Y)
 @constraint(m, Y in Exactly(1)) #logical constraint
+@objective(m, Max, sum(x))
+print(m)
+# Max x[1] + x[2]
+# Subject to
+#  x[1] ≥ 0
+#  x[2] ≥ 0
+#  x[1] ≤ 20
+#  x[2] ≤ 20
 
-## Big-M
-reformulate_model(m, BigM(100, false)) #specify M value and disable M-tightening
+##
+optimize!(m, method = BigM(100, false)) #specify M value and disable M-tightening
 print(m)
-# Feasibility
+# Max x[1] + x[2]
 # Subject to
 #  Y[1] + Y[2] = 1
 #  x[1] - 100 Y[1] ≥ -98
@@ -164,10 +173,10 @@ print(m)
 #  Y[1] binary
 #  Y[2] binary
 
-## Hull
-reformulate_model(m, Hull())
+##
+optimize!(m, method = Hull())
 print(m)
-# Feasibility
+# Max x[1] + x[2]
 # Subject to
 #  -x[2] + x[2]_Y[1] + x[2]_Y[2] = 0
 #  -x[1] + x[1]_Y[1] + x[1]_Y[2] = 0
@@ -202,21 +211,8 @@ print(m)
 #  x[1]_Y[2] ≤ 20
 #  Y[1] binary
 #  Y[2] binary
-
-## Indicator
-reformulate_model(m, Indicator())
-print(m)
-# Feasibility
-# Subject to
-#  Y[1] + Y[2] = 1
-#  x[1] ≥ 0
-#  x[2] ≥ 0
-#  x[1] ≤ 20
-#  x[2] ≤ 20
-#  Y[1] binary
-#  Y[2] binary
-#  Y[1] => {x[1] ∈ [2, 6]}
-#  Y[1] => {x[2] ∈ [5, 9]}
-#  Y[2] => {x[1] ∈ [8, 11]}
-#  Y[2] => {x[2] ∈ [10, 15]}
 ```
+
+## Contributing
+`DisjunctiveProgramming` is being actively developed and suggestions or other forms of contribution are encouraged.
+There are many ways to contribute to this package. Feel free to create an issue to address questions or provide feedback.

docs/make.jl

@@ -4,7 +4,8 @@ makedocs(
     sitename = "DisjunctiveProgramming.jl",
     modules  = [DisjunctiveProgramming],
     pages=[
-        "Home" => "index.md"
+        "Home" => "index.md",
+        "API" => "api.md"
     ],
     checkdocs = :none
 )

docs/src/api.md

@@ -0,0 +1,6 @@
+# API
+
+```@autodocs
+Modules = [DisjunctiveProgramming]
+Order   = [:type, :function]
+```

docs/src/assets/logo.png

@@ -1,2 +1,218 @@
-# Overview
-DisjunctiveProgramming.jl
+# DisjunctiveProgramming.jl
+Generalized Disjunctive Programming (GDP) extension to JuMP, based on the GDP modeling paradigm described in [Perez and Grossmann, 2023](https://arxiv.org/abs/2303.04375).
+
+![](assets/logo.png)
+
+[![codecov](https://codecov.io/gh/hdavid16/DisjunctiveProgramming.jl/graph/badge.svg?token=3FRPGMWF0J)](https://codecov.io/gh/hdavid16/DisjunctiveProgramming.jl)
+[![Docs](https://img.shields.io/badge/docs-stable-blue.svg)](https://hdavid16.github.io/InventoryManagement.jl/stable/)
+[![Docs](https://img.shields.io/badge/docs-latest-blue.svg)](https://hdavid16.github.io/InventoryManagement.jl/dev/)
+
+## Installation
+
+```julia
+using Pkg
+Pkg.add("DisjunctiveProgramming")
+```
+
+## Model
+
+A generalized disjunctive programming (GDP) model is created using `GDPModel()`, where the optimizer can be passed at model creation, along with other keyword arguments supported by JuMP Models. 
+
+```julia
+using DisjunctiveProgramming
+using HiGHS
+
+model = GDPModel(HiGHS.Optimizer)
+```
+
+A `GDPModel` is a `JuMP Model` with a `GDPData` field in the model's `.ext` dictionary, which stores the following:
+
+- `Logical Variables`: Indicator variables used for the various disjuncts involved in the model's disjunctions.
+- `Logical Constraints`: Selector (cardinality) or proposition (Boolean) constraints describing the relationships between the logical variables.
+- `Disjunct Constraints`: Constraints associated with each disjunct in the model.
+- `Disjunctions`: Disjunction constraints.
+- `Solution Method`: The reformulation technique or solution method. Currently supported methods include Big-M, Hull, and Indicator Constraints.
+- `Reformulation Variables`: List of JuMP variables created when reformulating a GDP model into a MIP model.
+- `Reformulation Constraints`: List of constraints created when reformulating a GDP model into a MIP model.
+- `Ready to Optimize`: Flag indicating if the model can be optimized.
+
+Additionally, the following mapping dictionaries are stored in `GDPData`:
+
+- `Indicator to Binary`: Maps the Logical variables to their respective reformulated Binary variables.
+- `Indicator to Constraints`: Maps the Logical variables to the disjunct constraints associated with them.
+
+A GDP Model's `GDPData` can be accessed via:
+
+```julia
+data = gdp_data(model)
+```
+
+## Logical Variables
+
+Logical variables are JuMP `AbstractVariable`s with two fields: `fix_value` and `start_value`. These can be optionally specified at variable creation. Logical variables are created with the `@variable` JuMP macro by adding the tag `Logical` as the last keyword argument. As with the regular `@variable` macro, variables can be named and indexed: 
+
+```julia
+@variable(model, Y[1:3], Logical)
+```
+
+## Logical Constraints
+
+Two types of logical constraints are supported:
+
+1. `Selector` or cardinality constraints: A subset of Logical variables is passed and `Exactly`, `AtMost`, or `AtLeast` `n` of these is allowed to be `True`. These constraints are specified with the `func` $\in$ `set` notation in `MathOptInterface` in a `@constraint` JuMP macro. It is not assumed that disjunctions have an `Exactly(1)` constraint enforced on their disjuncts upon creation. This constraint must be explicitly specified.
+
+    ```julia
+    @constraint(model, [Y[1], Y[2]] in Exactly(1))
+    ```
+
+2. `Proposition` or Boolean constraints: These describe the relationships between Logical variables via Boolean algebra. Supported logical operators include:
+
+    - `∨` or `logical_or` (OR, typed with `\vee + tab`).
+    - `∧` or `logical_and` (AND, typed with `\wedge + tab`).
+    - `¬` or `logical_not` (NOT, typed with `\neg + tab`).
+    - `⟹` of `implies` (Implication, typed with `\Longrightarrow + tab`).
+    - `⇔` or `iff` (double implication or equivalence, typed with `\Leftrightarrow + tab`).
+
+    The `@constraint` JuMP macro is used to create these constraints with the `IsTrue` set:
+
+    ```julia
+    @constraint(model, (Y[1] ⟹ Y[2]) in IsTrue())
+    ```
+
+    _Note_: The parenthesis in the example above around the implication clause are only required when the parent logical operator is `⟹` or `⇔` to avoid parsing errors.
+
+    Logical propositions can be reformulated to IP constraints by automatic reformulation to [Conjunctive Normal Form](https://en.wikipedia.org/wiki/Conjunctive_normal_form).
+
+## Disjunctions
+
+Disjunctions are built by first defining the constraints associated with each disjunct. This is done via the `@constraint` JuMP macro with the extra `DisjunctConstraint` tag specifying the Logical variable associated with the constraint:
+
+```julia
+@variable(model, x)
+@constraint(model, x ≤ 100, DisjunctConstraint(Y[1]))
+@constraint(model, x ≥ 200, DisjunctConstraint(Y[2]))
+```
+
+After all disjunct constraints associated with a disjunction have been defined, the disjunction is created with the `@disjunction` macro, where the disjunction is defined as a `Vector` of Logical variables associated with each disjunct:
+
+```julia
+@disjunction(model, [Y[1], Y[2]])
+```
+
+Disjunctions can be nested by passing an additional `DisjunctConstraint` tag. The Logical variable in the `DisjunctConstraint` tag specifies which disjunct, the nested disjunction belongs to:
+
+```julia
+@disjunction(model, Y[1:2], DisjunctConstraint(Y[3]))
+```
+
+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.
+
+## MIP Reformulations
+
+The following reformulation methods are currently supported:
+
+1. [Big-M](https://optimization.cbe.cornell.edu/index.php?title=Disjunctive_inequalities#Big-M_Reformulation[1][2]): The `BigM` struct is created with the following optional arguments:
+
+    - `value`: Big-M value to use. Default: `1e9`. Big-M values are currently global to the model. Constraint specific Big-M values can be supported in future releases.
+    - `tighten`: Boolean indicating if tightening the Big-M value should be attempted (currently supported only for linear disjunct constraints when variable bounds have been set or specified in the `variable_bounds` field). Default: `true`.
+    - `variable_bounds`: Dictionary specifying the lower and upper bounds for each `VariableRef` (e.g., `Dict(x => (lb, ub))`). Default: populate when calling the reformulation method.
+
+2. [Hull](https://optimization.cbe.cornell.edu/index.php?title=Disjunctive_inequalities#Convex-Hull_Reformulation[1][2]): The `Hull` struct is created with the following optional arguments:
+
+    - `value`: `ϵ` value to use when reformulating quadratic or nonlinear constraints via the perspective function proposed by [Furman, et al. [2020]](https://link.springer.com/article/10.1007/s10589-020-00176-0). Default: `1e-6`. `ϵ` values are currently global to the model. Constraint specific tolerances can be supported in future releases.
+    - `variable_bounds`: Dictionary specifying the lower and upper bounds for each `VariableRef` (e.g., `Dict(x => (lb, ub))`). Default: populate when calling the reformulation method.
+
+3. [Indicator](https://jump.dev/JuMP.jl/stable/manual/constraints/#Indicator-constraints): This method reformulates each disjunct constraint into an indicator constraint with the Boolean reformulation counterpart of the Logical variable used to define the disjunct constraint.
+
+## Release Notes
+
+Prior to `v0.4.0`, the package did not leverage the JuMP extension capabilities and was not as robust. For these earlier releases, refer to [Perez, Joshi, and Grossmann, 2023](https://arxiv.org/abs/2304.10492v1) and the following [JuliaCon 2022 Talk](https://www.youtube.com/watch?v=AMIrgTTfUkI).
+
+## Example
+
+The example below is from the [Cornell University Computational Optimization Open Textbook](https://optimization.cbe.cornell.edu/index.php?title=Disjunctive_inequalities#Big-M_Reformulation[1][2]).
+
+```julia
+using DisjunctiveProgramming
+using HiGHS
+
+m = GDPModel(HiGHS.Optimizer)
+@variable(m, 0 ≤ x[1:2] ≤ 20)
+@variable(m, Y[1:2], Logical)
+@constraint(m, [i = 1:2], [2,5][i] ≤ x[i] ≤ [6,9][i], DisjunctConstraint(Y[1]))
+@constraint(m, [i = 1:2], [8,10][i] ≤ x[i] ≤ [11,15][i], DisjunctConstraint(Y[2]))
+@disjunction(m, Y)
+@constraint(m, Y in Exactly(1)) #logical constraint
+@objective(m, Max, sum(x))
+print(m)
+# Max x[1] + x[2]
+# Subject to
+#  x[1] ≥ 0
+#  x[2] ≥ 0
+#  x[1] ≤ 20
+#  x[2] ≤ 20
+
+##
+optimize!(m, method = BigM(100, false)) #specify M value and disable M-tightening
+print(m)
+# Max x[1] + x[2]
+# Subject to
+#  Y[1] + Y[2] = 1
+#  x[1] - 100 Y[1] ≥ -98
+#  x[2] - 100 Y[1] ≥ -95
+#  x[1] - 100 Y[2] ≥ -92
+#  x[2] - 100 Y[2] ≥ -90
+#  x[1] + 100 Y[1] ≤ 106
+#  x[2] + 100 Y[1] ≤ 109
+#  x[1] + 100 Y[2] ≤ 111
+#  x[2] + 100 Y[2] ≤ 115
+#  x[1] ≥ 0
+#  x[2] ≥ 0
+#  x[1] ≤ 20
+#  x[2] ≤ 20
+#  Y[1] binary
+#  Y[2] binary
+
+##
+optimize!(m, method = Hull())
+print(m)
+# Max x[1] + x[2]
+# Subject to
+#  -x[2] + x[2]_Y[1] + x[2]_Y[2] = 0
+#  -x[1] + x[1]_Y[1] + x[1]_Y[2] = 0
+#  Y[1] + Y[2] = 1
+#  -2 Y[1] + x[1]_Y[1] ≥ 0
+#  -5 Y[1] + x[2]_Y[1] ≥ 0
+#  -8 Y[2] + x[1]_Y[2] ≥ 0
+#  -10 Y[2] + x[2]_Y[2] ≥ 0
+#  x[2]_Y[1]_lower_bound : -x[2]_Y[1] ≤ 0
+#  x[2]_Y[1]_upper_bound : -20 Y[1] + x[2]_Y[1] ≤ 0
+#  x[1]_Y[1]_lower_bound : -x[1]_Y[1] ≤ 0
+#  x[1]_Y[1]_upper_bound : -20 Y[1] + x[1]_Y[1] ≤ 0
+#  x[2]_Y[2]_lower_bound : -x[2]_Y[2] ≤ 0
+#  x[2]_Y[2]_upper_bound : -20 Y[2] + x[2]_Y[2] ≤ 0
+#  x[1]_Y[2]_lower_bound : -x[1]_Y[2] ≤ 0
+#  x[1]_Y[2]_upper_bound : -20 Y[2] + x[1]_Y[2] ≤ 0
+#  -6 Y[1] + x[1]_Y[1] ≤ 0
+#  -9 Y[1] + x[2]_Y[1] ≤ 0
+#  -11 Y[2] + x[1]_Y[2] ≤ 0
+#  -15 Y[2] + x[2]_Y[2] ≤ 0
+#  x[1] ≥ 0
+#  x[2] ≥ 0
+#  x[2]_Y[1] ≥ 0
+#  x[1]_Y[1] ≥ 0
+#  x[2]_Y[2] ≥ 0
+#  x[1]_Y[2] ≥ 0
+#  x[1] ≤ 20
+#  x[2] ≤ 20
+#  x[2]_Y[1] ≤ 20
+#  x[1]_Y[1] ≤ 20
+#  x[2]_Y[2] ≤ 20
+#  x[1]_Y[2] ≤ 20
+#  Y[1] binary
+#  Y[2] binary
+```
+
+## Contributing
+`DisjunctiveProgramming` is being actively developed and suggestions or other forms of contribution are encouraged.
+There are many ways to contribute to this package. Feel free to create an issue to address questions or provide feedback.