Merge pull request #49 from joaquimg/jg/readme2

improve readme

Project.toml

@@ -1,6 +1,6 @@
 name = "BilevelJuMP"
 uuid = "485130c0-026e-11ea-0f1a-6992cd14145c"
-authors = ["Joaquim Garcia <[email protected]>"]
+authors = ["Joaquim Garcia <[email protected]>, guilhermebodin <[email protected]>"]
 version = "0.1.0"
 
 [deps]
@@ -18,12 +18,8 @@ julia = "1"
 [extras]
 Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
 Cbc = "9961bab8-2fa3-5c5a-9d89-47fab24efd76"
-GLPK = "60bf3e95-4087-53dc-ae20-288a0d20c6a6"
-MathOptFormat = "f4570300-c277-12e8-125c-4912f86ce65d"
 Ipopt = "b6b21f68-93f8-5de0-b562-5493be1d77c9"
-Xpress = "9e70acf3-d6c9-5be6-b5bd-4e2c73e3e054"
-Gurobi = "2e9cd046-0924-5485-92f1-d5272153d98b"
 QuadraticToBinary = "014a38d5-7acb-4e20-b6c0-4fe5c2344fd1"
 
 [targets]
-test = ["Test", "Cbc", "GLPK", "MathOptFormat", "Ipopt", "Xpress", "Gurobi", "QuadraticToBinary"]
+test = ["Test", "Cbc", "Ipopt", "QuadraticToBinary"]

README.md

@@ -1,6 +1,6 @@
 # BilevelJuMP.jl
 
-Bilevel formulations in JuMP
+A bilevel optimization extension of the [JuMP](https://github.com/JuliaOpt/JuMP.jl) package.
 
 | **Build Status** |
 |:----------------:|
@@ -11,3 +11,47 @@ Bilevel formulations in JuMP
 [build-url]: https://travis-ci.org/joaquimg/BilevelJuMP.jl
 [codecov-img]: http://codecov.io/github/joaquimg/BilevelJuMP.jl/coverage.svg?branch=master
 [codecov-url]: http://codecov.io/github/joaquimg/BilevelJuMP.jl?branch=master
+
+## Introduction
+
+BilevelJuMP is a package for modeling and solving bilevel optimization problems in Julia. As an extension of the JuMP package, BilevelJuMP allows users to employ the usual JuMP syntax with minor modifications to describe the problem and query solutions.
+
+BilevelJuMP is built on top of [MathOptInterface](https://github.com/JuliaOpt/MathOptInterface.jl) and makes strong use of its features to reformulate the problem as a single level problem and solve it with available MIP, NLP, and other solvers.
+
+The currently available methods are based on re-writing the problem using the KKT conditions of the lower level. For that we make strong use of [Dualization.jl](https://github.com/JuliaOpt/Dualization.jl)
+
+## Example
+
+```julia
+using JuMP, BilevelJuMP, Xpress
+
+model = BilevelModel()
+
+@variable(Lower(model), x)
+@variable(Upper(model), y)
+
+@objective(Upper(model), Min, 3x + y)
+@constraints(Upper(model), begin
+    x <= 5
+    y <= 8
+    y >= 0
+end)
+
+@objective(Lower(model), Min, -x)
+@constraint(Lower(model), begin
+     x +  y <= 8
+    4x +  y >= 8
+    2x +  y <= 13
+    2x - 7y <= 0
+end)
+
+optimize!(model, Xpress.Optimizer(), BilevelJuMP.SOS1Mode())
+
+objective_value(model) # = 3 * (3.5 * 8/15) + 8/15
+value(x) # = 3.5 * 8/15
+value(y) # = 8/15
+```
+
+The option `BilevelJuMP.SOS1Mode()` indicates that the solution method used will be a KKT reformulation emplying SOS1 to model complementarity constraints and solve the problem with MIP solvers (Cbc, Xpress, Gurobi, CPLEX).
+
+Another option is `BilevelJuMP.ProductMode()` that reformulates the complementarity constraints as products so that the problem can be solved by NLP (Ipopt, KNITRO) solvers or even MIP solver with the aid of binary expansions (see [QuadraticToBinary.jl](https://github.com/joaquimg/QuadraticToBinary.jl)).

src/jump.jl

@@ -761,12 +761,12 @@ function replace_variables(quad::JuMP.GenericQuadExpr{C, BilevelVariableRef},
 end
 replace_variables(funcs::Vector, args...) = map(f -> replace_variables(f, args...), funcs)
 
-using MathOptFormat
-function print_lp(m, name)
-    lp_model = MathOptFormat.MOF.Model()
-    MOI.copy_to(lp_model, m)
-    MOI.write_to_file(lp_model, name)
-end
+# using MathOptFormat
+# function print_lp(m, name)
+#     lp_model = MathOptFormat.MOF.Model()
+#     MOI.copy_to(lp_model, m)
+#     MOI.write_to_file(lp_model, name)
+# end
 
 JuMP.optimize!(::T) where {T<:AbstractBilevelModel} = 
     error("cant solve a model of type: $T ")

test/runtests.jl

@@ -62,7 +62,7 @@ end
         jump_05(solver.opt, solver.mode)
         #jump_3SAT(solver.opt, solver.mode)
         jump_06(solver.opt, solver.mode)
-        jump_07(solver.opt, solver.mode)
+        jump_07(solver.opt, solver.mode, CONFIG_3)
         jump_08(solver.opt, solver.mode)
         jump_09a(solver.opt, solver.mode)
         jump_09b(solver.opt, solver.mode)