Add NonlinearExpr and new nonlinear interface (#3106)

Project.toml

@@ -5,6 +5,7 @@ version = "1.14.0"
 
 [deps]
 LinearAlgebra = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e"
+MacroTools = "1914dd2f-81c6-5fcd-8719-6d5c9610ff09"
 MathOptInterface = "b8f27783-ece8-5eb3-8dc8-9495eed66fee"
 MutableArithmetics = "d8a4904e-b15c-11e9-3269-09a3773c0cb0"
 OrderedCollections = "bac558e1-5e72-5ebc-8fee-abe8a469f55d"
@@ -20,8 +21,9 @@ JuMPDimensionalDataExt = "DimensionalData"
 
 [compat]
 DimensionalData = "0.24"
-MathOptInterface = "1.18"
-MutableArithmetics = "1"
+MacroTools = "0.5"
+MathOptInterface = "1.19"
+MutableArithmetics = "1.1"
 OrderedCollections = "1"
 SnoopPrecompile = "1"
 julia = "1.6"

docs/Project.toml

@@ -20,11 +20,13 @@ Markdown = "d6f4376e-aef5-505a-96c1-9c027394607a"
 MarkdownAST = "d0879d2d-cac2-40c8-9cee-1863dc0c7391"
 MathOptInterface = "b8f27783-ece8-5eb3-8dc8-9495eed66fee"
 MultiObjectiveAlgorithms = "0327d340-17cd-11ea-3e99-2fd5d98cecda"
+PATHSolver = "f5f7c340-0bb3-5c69-969a-41884d311d1b"
 Pkg = "44cfe95a-1eb2-52ea-b672-e2afdf69b78f"
 Plots = "91a5bcdd-55d7-5caf-9e0b-520d859cae80"
 Random = "9a3f8284-a2c9-5f02-9a11-845980a1fd5c"
 SCS = "c946c3f1-0d1f-5ce8-9dea-7daa1f7e2d13"
 SQLite = "0aa819cd-b072-5ff4-a722-6bc24af294d9"
+SpecialFunctions = "276daf66-3868-5448-9aa4-cd146d93841b"
 StatsPlots = "f3b207a7-027a-5e70-b257-86293d7955fd"
 TOML = "fa267f1f-6049-4f14-aa54-33bafae1ed76"
 Tables = "bd369af6-aec1-5ad0-b16a-f7cc5008161c"
@@ -48,6 +50,7 @@ JSONSchema = "1"
 Literate = "2.8"
 MathOptInterface = "=1.19.0"
 MultiObjectiveAlgorithms = "=1.2.0"
+PATHSolver = "=1.6.0"
 Plots = "1"
 SCS = "=1.3.0"
 SQLite = "1"

docs/make.jl

@@ -308,6 +308,7 @@ const _PAGES = [
             "tutorials/nonlinear/user_defined_hessians.md",
             "tutorials/nonlinear/nested_problems.md",
             "tutorials/nonlinear/querying_hessians.md",
+            "tutorials/nonlinear/complementarity.md",
         ],
         "Conic programs" => [
             "tutorials/conic/introduction.md",
@@ -345,6 +346,7 @@ const _PAGES = [
         "manual/nlp.md",
         "manual/callbacks.md",
         "manual/complex.md",
+        "manual/nonlinear.md",
     ],
     jump_api_reference,
     "Background Information" =>

docs/src/manual/expressions.md

@@ -195,7 +195,7 @@ julia> @variable(model, y)
 y
 
 julia> ex = @expression(model, x^2 + 2 * x * y + y^2 + x + y - 1)
-x² + 2 y*x + y² + x + y - 1
+x² + 2 x*y + y² + x + y - 1
 ```
 
 ### Operator overloading
@@ -326,10 +326,8 @@ julia> coefficient(ex, x)
 
 ## Nonlinear expressions
 
-Nonlinear expressions can be constructed only using the [`@NLexpression`](@ref)
-macro and can be used only in [`@NLobjective`](@ref), [`@NLconstraint`](@ref),
-and other [`@NLexpression`](@ref)s. For more details, see the [Nonlinear
-Modeling](@ref) section.
+Nonlinear expressions in JuMP are represented by a [`NonlinearExpr`](@ref)
+object. See [Nonlinear expressions in detail](@ref) for more details.
 
 ## Initializing arrays
 

docs/src/manual/nlp.md

@@ -8,6 +8,13 @@ DocTestFilters = [r"≤|<=", r"≥|>=", r" == | = ", r" ∈ | in ", r"MathOptInt
 
 # Nonlinear Modeling
 
+!!! warning
+    This page describes the legacy nonlinear interface to JuMP. It has a number
+    of quirks and limitations that prompted the development of a new nonlinear
+    interface. The new interface is documented at [Nonlinear Modeling](@ref new_nonlinear_interface).
+    This legacy interface will remain for all future `v1.X` releases of JuMP.
+    The two nonlinear interfaces cannot be combined.
+
 JuMP has support for general smooth nonlinear (convex and nonconvex)
 optimization problems. JuMP is able to provide exact, sparse second-order
 derivatives to solvers. This information can improve solver accuracy and
@@ -172,22 +179,7 @@ julia> value.(p)
  3.0
 ```
 
-Nonlinear parameters can be used *within nonlinear macros* only:
-
-```jldoctest nonlinear_parameters
-julia> @objective(model, Max, p[1] * x)
-ERROR: MethodError: no method matching *(::NonlinearParameter, ::VariableRef)
-[...]
-
-julia> @NLobjective(model, Max, p[1] * x)
-
-julia> @expression(model, my_expr, p[1] * x^2)
-ERROR: MethodError: no method matching *(::NonlinearParameter, ::QuadExpr)
-[...]
-
-julia> @NLexpression(model, my_nl_expr, p[1] * x^2)
-subexpression[1]: parameter[1] * x ^ 2.0
-```
+Nonlinear parameters must be used *within nonlinear macros* only.
 
 ### When to use a parameter
 
@@ -220,27 +212,6 @@ nothing #hide
 The syntax accepted in nonlinear macros is more restricted than the syntax
 for linear and quadratic macros. We note some important points below.
 
-### No operator overloading
-
-There is no operator overloading provided to build up nonlinear expressions.
-For example, if `x` is a JuMP variable, the code `3x` will return an
-`AffExpr` object that can be used inside of future expressions and linear
-constraints. However, the code `sin(x)` is an error. All nonlinear
-expressions must be inside of macros.
-
-```jldoctest
-julia> model = Model();
-
-julia> @variable(model, x);
-
-julia> expr = sin(x) + 1
-ERROR: sin is not defined for type AbstractVariableRef. Are you trying to build a nonlinear problem? Make sure you use @NLconstraint/@NLobjective.
-[...]
-
-julia> expr = @NLexpression(model, sin(x) + 1)
-subexpression[1]: sin(x) + 1.0
-```
-
 ### Scalar operations only
 
 Except for the splatting syntax discussed below, all expressions
@@ -308,7 +279,7 @@ the function is not available in the scope of the nonlinear expression.
 
 !!! warning
     User-defined functions must return a scalar output. For a work-around, see
-    [User-defined functions with vector outputs](@ref).
+    [User-defined operators with vector outputs](@ref).
 
 ### Automatic differentiation