Data Structure Overhaul

.travis.yml

@@ -4,10 +4,8 @@ os:
   - linux
 julia:
   - 1.0
-  - 1.1
-  - 1.2
-  - 1.3
   - 1.4
+  - 1.5
   - nightly
 notifications:
   email: false
@@ -16,8 +14,8 @@ after_success:
 jobs:
   include:
     - os: osx
-      julia: 1.4
-      name: "Julia: 1.4"
+      julia: 1.5
+      name: "Julia: 1.5"
     # - os: windows
     #   # arch: x64
     #   julia: 1.3

Project.toml

@@ -1,27 +1,26 @@
 name = "InfiniteOpt"
 uuid = "20393b10-9daf-11e9-18c9-8db751c92c57"
 authors = ["Joshua Pulsipher and Weiqi Zhang"]
-version = "0.1.1"
+version = "0.2.0"
 
 [deps]
 JuMP = "4076af6c-e467-56ae-b986-b466b2749572"
-LinearAlgebra = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e"
 MathOptInterface = "b8f27783-ece8-5eb3-8dc8-9495eed66fee"
 Distributions = "31c24e10-a181-5473-b8eb-7969acd0382f"
-Random = "9a3f8284-a2c9-5f02-9a11-845980a1fd5c"
 FastGaussQuadrature = "442a2c76-b920-505d-bb47-c5924d526838"
-MutableArithmetics = "d8a4904e-b15c-11e9-3269-09a3773c0cb0"
+DataStructures = "864edb3b-99cc-5e75-8d2d-829cb0a9cfe8"
 
 [compat]
 julia = "1"
-JuMP = "~0.21"
+JuMP = "~0.21.4"
 FastGaussQuadrature = "^0.3.2, ~0.4"
 Distributions = "~0.19, ~0.20, ~0.21, ~0.22, ~0.23"
-MathOptInterface = "~0.9.11"
-MutableArithmetics = "~0.2"
+MathOptInterface = "=0.9.14"
+DataStructures = "^0.14.2, ~0.15, ~0.16, ~0.17, ~0.18"
 
 [extras]
 Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
+Random = "9a3f8284-a2c9-5f02-9a11-845980a1fd5c"
 
 [targets]
-test = ["Test"]
+test = ["Test", "Random"]

README.md

@@ -50,7 +50,7 @@ Comments, suggestions and improvements are welcome and appreciated.
 following in the package manager.
 
 ```julia
-(v1.4) pkg> add InfiniteOpt
+(v1.5) pkg> add InfiniteOpt
 ```
 
 ## Documentation
@@ -60,7 +60,7 @@ Please visit our [documentation pages](https://pulsipher.github.io/InfiniteOpt.j
 tutorials, examples, and more!
 
 ## Project Status
-The package is tested against Julia `1.0`, `1.1`, `1.2`, `1.3`, `1.4`, and nightly on Linux, macOS, and Windows.
+The package is tested against Julia `1.0`, `1.4`, `1.5`, and nightly on Linux, macOS, and Windows.
 
 ## Contributing
 `InfiniteOpt` is being actively developed and suggestions or other forms of contribution are encouraged.

appveyor.yml

@@ -1,6 +1,6 @@
 environment:
   matrix:
-  - julia_version: 1.4
+  - julia_version: 1.5
 
 platform:
   - x86 # 32-bit

docs/Project.toml

@@ -4,6 +4,7 @@ JuMP = "4076af6c-e467-56ae-b986-b466b2749572"
 MathOptInterface = "b8f27783-ece8-5eb3-8dc8-9495eed66fee"
 Ipopt = "b6b21f68-93f8-5de0-b562-5493be1d77c9"
 Distributions = "31c24e10-a181-5473-b8eb-7969acd0382f"
+Random = "9a3f8284-a2c9-5f02-9a11-845980a1fd5c"
 
 [compat]
-Documenter = "≥ 0.24.2"
+Documenter = "~0.25"

docs/README.md

@@ -0,0 +1,15 @@
+# Documentation Builds
+InfiniteOpt.jl's documentation is written with [Documenter.jl](https://github.com/JuliaDocs/Documenter.jl). 
+To install it, run the following command in a Julia session:
+
+```julia
+julia> ] 
+
+(v1.5) pkg> add Documenter
+```
+
+Once you have Documenter installed you can build the documentation via:
+```julia
+julia --project=. --color=yes make.jl
+```
+The compiled documents can then be viewed at `build/index.html`.

docs/make.jl

@@ -14,19 +14,28 @@ makedocs(;
                              "Constraints" => "guide/constraint.md",
                              "Model Transcription" => "guide/transcribe.md",
                              "Optimization" => "guide/optimize.md",
-                             "Results" => "guide/result.md"],
+                             "Results" => "guide/result.md"
+                             ]
+                             ,
             "Examples" => "examples.md",
             "Extensions" => "extensions.md",
             "Development" => "develop.md",
             "Library" => "library.md",
-            hide("JuMP Docs" => "JuMP.md")],
+            hide("JuMP Docs" => "JuMP.md")
+            ],
     repo = "https://github.com/pulsipher/InfiniteOpt.jl/blob/{commit}{path}#L{line}",
     sitename = "InfiniteOpt.jl",
     authors = "Joshua Pulsipher and Weiqi Zhang",
     doctest = true,
-    linkcheck = true
+    linkcheck = true,
+    format = Documenter.HTML(
+        # See https://github.com/JuliaDocs/Documenter.jl/issues/868
+        prettyurls = get(ENV, "CI", nothing) == "true",
+        analytics = "UA-178297470-1",
+    )
 )
 
 deploydocs(;
     repo = "github.com/pulsipher/InfiniteOpt.jl",
 )
+

docs/src/JuMP.md

@@ -14,6 +14,7 @@ JuMP.Model()
 JuMP.Model(::Any)
 JuMP.NoOptimizer
 JuMP.optimizer_with_attributes(::Any, ::Pair)
+JuMP.direct_model
 ```
 
 ## Variables
@@ -57,6 +58,12 @@ JuMP.IntegerRef(::JuMP.VariableRef)
 JuMP.unset_integer(::JuMP.VariableRef)
 ```
 
+## Containers 
+```@docs
+JuMP.Containers.SparseAxisArray
+JuMP.Containers.DenseAxisArray
+```
+
 ## Expressions
 ```@docs
 JuMP.@expression
@@ -113,6 +120,7 @@ JuMP.set_optimizer_attribute(::JuMP.Model, ::MOI.AbstractOptimizerAttribute, ::A
 JuMP.set_optimizer_attributes(::JuMP.Model, ::Pair)
 JuMP.get_optimizer_attribute(::JuMP.Model, ::String)
 JuMP.get_optimizer_attribute(::JuMP.Model, ::MOI.AbstractOptimizerAttribute)
+JuMP.set_optimizer(::JuMP.Model, ::Any)
 JuMP.result_count(::JuMP.Model)
 ```
 
@@ -136,4 +144,100 @@ JuMP.optimizer_index(::JuMP.VariableRef)
 JuMP.optimizer_index(::JuMP.ConstraintRef{JuMP.Model})
 JuMP.lp_rhs_perturbation_range(::JuMP.ConstraintRef{JuMP.Model, <:JuMP._MOICON})
 JuMP.lp_objective_perturbation_range(::JuMP.VariableRef)
+JuMP.reduced_cost(::VariableRef)
+```
+
+# JuMP Section References
+## Containers in macros
+The `container` function encodes the logic for how containers are
+constructed in JuMP's macros. The `@container` macro is available to create
+containers independently of any JuMP model.
+```@docs
+JuMP.Containers.container
+JuMP.Containers.default_container
+JuMP.Containers.VectorizedProductIterator
+JuMP.Containers.NestedIterator
+JuMP.Containers.@container
 ```
+
+In the [`@variable`](@ref) (resp. [`@constraint`](@ref)) macro, containers of
+variables (resp. constraints) can be created with the following syntax:
+
+* `name[index_set_1, index_set_2, ..., index_set_n]` creating an `n`-dimensional
+  container of name `name`; or
+* `[index_set_1, index_set_2, ..., index_set_n]` creating an *anonymous*
+  `n`-dimensional container.
+
+Each expression `index_set_i` can either be
+
+* of the form `index_set` specifying that the `i`th index set of the container
+  is `index_set`; or
+* of the form `index_name=index_set` specifying that the `i`th index set of the
+  container is `index_set` and allowing values used in the macro expression and
+  keyword arguments to be expressions depending on the `index_name`.
+
+The macro then creates the container using the
+[`JuMP.Containers.container`](@ref) function with the following
+arguments:
+
+1. A function taking as argument the value of the indices and returning the
+   value to be stored in the container, e.g. a variable for the
+   [`@variable`](@ref) macro and a constraint for the [`@constraint`](@ref)
+   macro.
+2. An iterator over the indices of the container.
+4. The value of the `container` keyword argument if given.
+
+## Variables constrained on creation
+!!! info
+    When using JuMP in Direct mode, it may be required to constrain
+    variables on creation instead of constraining free variables as the solver
+    may only support variables constrained on creation. In Automatic and Manual
+    modes, both ways of adding constraints on variables are equivalent.
+    Indeed, during the copy of the cache to the optimizer, the choice of the
+    constraints on variables that are copied as variables constrained on creation
+    does not depend on how it was added to the cache.
+
+All uses of the `@variable` macro documented so far translate to a separate
+call for variable creation and adding of constraints.
+
+For example, `@variable(model, x >= 0, Int)`, is equivalent to:
+```julia
+@variable(model, x)
+set_lower_bound(x, 0.0)
+@constraint(model, x in MOI.Integer())
+```
+Importantly, the bound and integrality constraints are added _after_ the
+variable has been created.
+
+However, some solvers require a constraining set _at creation time_.
+We say that these variables are _constrained on creation_.
+
+Use `in` within `@variable` to access the special syntax for constraining
+variables on creation. For example, the following creates a vector of variables
+constrained on creation to belong to the `SecondOrderCone`:
+```julia-repl
+julia> @variable(model, y[1:3] in SecondOrderCone())
+3-element Array{VariableRef,1}:
+ y[1]
+ y[2]
+ y[3]
+```
+
+For contrast, the more standard approach is as follows:
+```julia-repl
+julia> @variable(model, x[1:3])
+3-element Array{VariableRef,1}:
+ x[1]
+ x[2]
+ x[3]
+
+julia> @constraint(model, x in SecondOrderCone())
+[x[1], x[2], x[3]] ∈ MathOptInterface.SecondOrderCone(3)
+```
+
+The technical difference between the former and the latter is that the former
+calls `MOI.add_constrained_variables` while the latter calls `MOI.add_variables`
+and then `MOI.add_constraint`. This distinction is important only in
+Direct mode, depending on the solver being used. It's often not
+possible to delete the `SecondOrderCone` constraint if it was specified
+at variable creation time.

docs/src/develop.md

@@ -38,7 +38,7 @@ through step by step how this should be done.
      computer. This needs to be done via the `dev` command in the package manager
      so you can edit it. The syntax is as follows:
      ```julia
-     (v1.3) pkg> dev https://github.com/username-here/InfiniteOpt.jl
+     (v1.5) pkg> dev https://github.com/username-here/InfiniteOpt.jl
      ```
      We also recommend you install [`Revise.jl`](https://github.com/timholy/Revise.jl)
      which is very useful when developing packages in Julia.
@@ -65,7 +65,7 @@ through step by step how this should be done.
   8. Create a pull request. Go [here](https://github.com/pulsipher/InfiniteOpt.jl)
      to `InfiniteOpt`'s main page and create a pull request drawing from your forked
      repository. A step by step explanation is provided
-     [here](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request-from-a-fork).
+     [here](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request-from-a-fork).
   9. Make necessary changes if the tests fail and/or we ask you to make specific
      changes. The Codecov tests will ensure every new line of code is tested at least
      once with the new test functions and Travis CI will ensure that the tests pass
@@ -139,7 +139,7 @@ Here we detail the programmatic style used with `InfiniteOpt`. This is done in a
 effort to make this package intuitive for new-comers and to ease development. This
 style closely follows that of `JuMP.jl` with similar deviations from typical Julia
 styles. Please refer to the `JuMP` style guide
-[here](http://www.juliaopt.org/JuMP.jl/stable/style/) as this is the style used
+[here](https://jump.dev/JuMP.jl/stable/style/) as this is the style used
 by `InfiniteOpt`.
 
 In addition, we adopt the following practices:
@@ -179,7 +179,7 @@ In addition, we adopt the following practices:
    end
    ```
  - All function arguments and struct elements should be typed. Also, function
-   outputs should be typed where possible unless nothing is returned.   
+   outputs should be typed where possible.   
    This is bad:
    ```julia
    function my_new_function(arg1, arg2)
@@ -203,7 +203,7 @@ In addition, we adopt the following practices:
  - Type dispatch should be used instead of conditional statements based on type:
    This is bad:
    ```julia
-   function my_new_function(arg::AbstractType)
+   function my_new_function(arg::AbstractType)::ReturnType
      if arg isa Type1
          temp = arg + 1
      elseif arg isa Type2
@@ -217,20 +217,19 @@ In addition, we adopt the following practices:
    ```julia
    ## Internal dispatch for my_new_function
    # Type1
-   function _my_internal_function(arg::Type1)
+   function _my_internal_function(arg::Type1)::Int
        return arg + 1
    end
    # Type2
-   function _my_internal_function(arg::Type1)
+   function _my_internal_function(arg::Type1)::Int
        return 0
    end
    # Fallback
    function _my_internal_function(arg::AbstractType)
        error("Unrecognized type...")
-       return
    end
    # Main method
-   function my_new_function(arg::AbstractType)
+   function my_new_function(arg::AbstractType)::ReturnType
      temp = _my_internal_function(arg)
      # do more stuff with temp
      return temp