update docs

Author: mohdibntarek

docs/src/algorithms/ipopt.md

@@ -27,11 +27,14 @@ alg = IpoptAlg()
 
 The options keyword argument to the `optimize` function shown above must be an instance of the `IpoptOptions` struct when the algorihm is an `IpoptAlg`. To specify options use keyword arguments in the constructor of `IpoptOptions`, e.g:
 ```julia
-options = IpoptOptions(first_order = false, tol = 1e-4, sparse = false)
+options = IpoptOptions(first_order = false, tol = 1e-4, sparse = false, symbolic = false)
 ```
-There are 3 important and special options:
+There are 4 important and special options:
 - `first_order`: `true` by default. When `first_order` is `true`, the first order Ipopt algorithm will be used. And when it is `false`, the second order Ipopt algorithm will be used.
-- `sparse`: `false` by default. When `sparse` is set to `true`, the gradients, Jacobians and Hessians of the function, constraint and Lagrangian functions will be treated as sparse vectors/matrices. In order to be effective, this should be combined with custom gradient/Hessian rules, sparsification or symbolification of some functions in the model. For more on custom gradients, sparsification and symbolification, see the [gradients section](../gradients/gradients.md) in the documentation.
+- `symbolic`: `false` by default. When `symbolic` is set to `true`, the gradients, Jacobians and Hessians of the objective, constraint and Lagrangian functions will be calculated using symbolic differentiation from [`Symbolics.jl`](https://github.com/JuliaSymbolics/Symbolics.jl). This is the same approach used by `symbolify` which is described in the [symbolic differentiation section](../gradients/symbolic.md) in the documentation.
+- `sparse`: `false` by default. When `sparse` is set to `true`, the gradients, Jacobians and Hessians of the objective, constraint and Lagrangian functions will be treated as sparse vectors/matrices. When combined with `symbolic = true`, the output of symbolic differentiation will be a sparse vector/matrix, akin to setting `sparse = true` in the `symbolify` function discussed in [symbolic differentiation section](../gradients/symbolic.md) in the documentation. When used alone with `symbolic = false`, [`SparseDiffTools.jl`](https://github.com/JuliaDiff/SparseDiffTools.jl) is used instead for the differentiation and `Symbolics` is only used to get the sparsity pattern, much like how `sparsify` works. For more details on `sparsify` and the way `SparseDiffTools` works, see the [sparsity section](../gradients/sparse.md) in the documentation is used instead.
 - `linear_constraints`:  `false` by default. When `linear_constraints` is `true`, the Jacobian of the constraints will be computed and sparsified once at the beginning. When it is `false`, dense Jacobians will be computed in every iteration.
 
+> Note that there is no need to use `sparsify` or `symbolify` on the model or functions before optimizing it with an `IpoptAlg`. Setting the `sparse` and `symbolic` options above are enough to trigger the symbolic differentiation and/or sparsity exploitation.
+
 All the other options that can be set can be found on the [Ipopt options](https://coin-or.github.io/Ipopt/OPTIONS.html) section of Ipopt's documentation.

docs/src/gradients/implicit.md

@@ -13,7 +13,7 @@ For more on implicit differentation, refer to the last part of the [_Understandi
 
 ## Relationship to [`ImplicitDifferentiation.jl`](https://github.com/gdalle/ImplicitDifferentiation.jl)
 
-[`ImplicitDifferentiation.jl`](https://github.com/gdalle/ImplicitDifferentiation.jl) is an attempt to simplify the implementation in `Nonconvex` making it more lightweight and better documented. For instance, the [documentation of `ImplicitDifferentiation`](https://gdalle.github.io/ImplicitDifferentiation.jl/) presents a number of examples of implicit functions all of which can be defined and used using `Nonconvex`.
+[`ImplicitDifferentiation.jl`](https://github.com/gdalle/ImplicitDifferentiation.jl) is an attempt to simplify the implementation in `Nonconvex` making it more lightweight and better documented. For instance, the [documentation of `ImplicitDifferentiation`](https://gdalle.github.io/ImplicitDifferentiation.jl/) presents a number of examples of implicit functions all of which can be defined using `Nonconvex` instead.
 
 ## Explicit parameters
 
@@ -78,9 +78,7 @@ In the adjoint definition of implicit functions, a linear system:
 ```julia
 (df/dy) * x = v
 ```
-is solved to find the adjoint vector. To solve the system using a matrix-free iterative solver (GMRES by default) that avoids constructing the Jacobian `df/dy`, you can set the `matrixfree` keyword argument to `true` (default is `false`).
-
-When set to `true`, the entrie Jacobian matrix is formed and the linear system is solved using LU factorization.
+is solved to find the adjoint vector. To solve the system using a matrix-free iterative solver (GMRES by default) that avoids constructing the Jacobian `df/dy`, you can set the `matrixfree` keyword argument to `true` (default is `false`). When set to `false`, the entrie Jacobian matrix is formed and the linear system is solved using LU factorization.
 
 ## Arbitrary data structures
 

docs/src/gradients/sparse.md

@@ -23,7 +23,7 @@ In order to force `Nonconvex` to use `SparseDiffTools` when differentiating a fu
 F = sparsify(f, x...; hessian = false)
 F(x...)
 ```
-where `x` is some sample input arguments to `f`. `F(x...)` can now be used inplace of `f(x...)` in objectives and/constraints to be differentiated. Whenever `ForwardDiff` or any `ChainRules`-compatible AD package such as `Zygote` is used to differentiate `F` once, `SparseDiffTools` will now be used.
+where `x` is some sample input arguments to `f`. `F(x...)` can now be used inplace of `f(x...)` in objectives and/or constraints to be differentiated. Whenever `ForwardDiff` or any `ChainRules`-compatible AD package such as `Zygote` is used to differentiate `F` once, `SparseDiffTools` will now be used.
 
 ### Second order derivatives
 

docs/src/gradients/symbolic.md

@@ -15,7 +15,7 @@ In order to force `Nonconvex` to use `Symbolics` when differentiating a function
 F = symbolify(f, x...; hessian = false, sparse = false, simplify = false)
 F(x...)
 ```
-where `x` is some sample input arguments to `f`. `F(x...)` can now be used inplace of `f(x...)` in objectives and/constraints to be differentiated. Whenever `ForwardDiff` or any `ChainRules`-compatible AD package such as `Zygote` is used to differentiate `F` once, the `Symbolics`-derived gradient/Jacobian will now be used.
+where `x` is some sample input arguments to `f`. `F(x...)` can now be used inplace of `f(x...)` in objectives and/or constraints to be differentiated. Whenever `ForwardDiff` or any `ChainRules`-compatible AD package such as `Zygote` is used to differentiate `F` once, the `Symbolics`-derived gradient/Jacobian will now be used.
 
 The `sparse` keyword argument can be set to `true` (default is `false`) to tell `Symbolics` to return a sparse gradient/Jacobian for the function `F`. The `simplify` keyword argument can be set to `true` (default is `false`) to tell `Symbolics` to simplify the mathematical expressions for the gradient/Jacobian functions.