From 8d2d0c33b87076f3a52d5f6abbb4afdc3a968294 Mon Sep 17 00:00:00 2001 From: Mohamed Tarek Date: Sat, 18 Jun 2022 07:22:39 +1000 Subject: [PATCH 1/5] add headers to sidebar --- docs/make.jl | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/docs/make.jl b/docs/make.jl index 31cce93f..b356672b 100644 --- a/docs/make.jl +++ b/docs/make.jl @@ -6,7 +6,16 @@ makedocs( pages = [ "Getting started" => "index.md", "Problem definition" => "problem/problem.md", - "Gradients, Jacobians and Hessians" => "gradients/gradients.md", + "Gradients, Jacobians and Hessians" => [ + "Overview" => "gradients/gradients.md", + "user_defined.md", + "other_ad.md", + "chainrules_fd.md", + "sparse.md", + "symbolic.md", + "implicit.md", + "history.md", + ], "Algorithms" => [ "Overview" => "algorithms/algorithms.md", "algorithms/mma.md", From cc4054f94fa063bcafbf68410ba1cf4183b286a4 Mon Sep 17 00:00:00 2001 From: Mohamed Tarek Date: Sat, 18 Jun 2022 07:25:08 +1000 Subject: [PATCH 2/5] 4 -> 3 --- README.md | 2 +- docs/src/index.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index a06380bd..c35cbb8b 100644 --- a/README.md +++ b/README.md @@ -31,7 +31,7 @@ The `JuliaNonconvex` organization hosts a number of packages which are available ## Design philosophy -Nonconvex.jl is a Julia package that implements and wraps a number of constrained nonlinear and mixed integer nonlinear programming solvers. There are 4 unique features of Nonconvex.jl compared to similar packages such as JuMP.jl and NLPModels.jl: +Nonconvex.jl is a Julia package that implements and wraps a number of constrained nonlinear and mixed integer nonlinear programming solvers. There are 3 features of Nonconvex.jl compared to similar packages such as JuMP.jl and NLPModels.jl: 1. Emphasis on a function-based API. Objectives and constraints are normal Julia functions. 2. The ability to nest algorithms to create more complicated algorithms. diff --git a/docs/src/index.md b/docs/src/index.md index 8f1df6de..9c49e6b9 100644 --- a/docs/src/index.md +++ b/docs/src/index.md @@ -1,6 +1,6 @@ # Nonconvex.jl Documentation -Nonconvex.jl is a Julia package that implements and wraps a number of constrained nonlinear and mixed integer nonlinear programming solvers. There are 4 unique features of Nonconvex.jl compared to similar packages such as JuMP.jl and NLPModels.jl: +Nonconvex.jl is a Julia package that implements and wraps a number of constrained nonlinear and mixed integer nonlinear programming solvers. There are 3 features of Nonconvex.jl compared to similar packages such as JuMP.jl and NLPModels.jl: 1. Emphasis on a function-based API. Objectives and constraints are normal Julia functions. 2. The ability to nest algorithms to create more complicated algorithms. From 0cf135f8057a43234d04c65e603c8c540021b089 Mon Sep 17 00:00:00 2001 From: Mohamed Tarek Date: Sat, 18 Jun 2022 07:31:29 +1000 Subject: [PATCH 3/5] fix paths --- docs/make.jl | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/make.jl b/docs/make.jl index b356672b..ada641f8 100644 --- a/docs/make.jl +++ b/docs/make.jl @@ -8,13 +8,13 @@ makedocs( "Problem definition" => "problem/problem.md", "Gradients, Jacobians and Hessians" => [ "Overview" => "gradients/gradients.md", - "user_defined.md", - "other_ad.md", - "chainrules_fd.md", - "sparse.md", - "symbolic.md", - "implicit.md", - "history.md", + "gradients/user_defined.md", + "gradients/other_ad.md", + "gradients/chainrules_fd.md", + "gradients/sparse.md", + "gradients/symbolic.md", + "gradients/implicit.md", + "gradients/history.md", ], "Algorithms" => [ "Overview" => "algorithms/algorithms.md", From 9a4db68e6f02626566a1b25ee7703bc13e1e9f03 Mon Sep 17 00:00:00 2001 From: Mohamed Tarek Date: Sat, 18 Jun 2022 07:44:09 +1000 Subject: [PATCH 4/5] add table of contents sections --- docs/src/gradients/gradients.md | 2 ++ docs/src/problem/problem.md | 2 ++ 2 files changed, 4 insertions(+) diff --git a/docs/src/gradients/gradients.md b/docs/src/gradients/gradients.md index e848e9ee..45439e09 100644 --- a/docs/src/gradients/gradients.md +++ b/docs/src/gradients/gradients.md @@ -13,6 +13,8 @@ In some cases, function modifiers can even be composed on top of each other to c > In `Nonconvex`, function modifiers modify the behaviour of a function when differentiated once or twice using either `ForwardDiff` or any [`ChainRules`](https://github.com/JuliaDiff/ChainRules.jl)-compatible AD package, such as `Zygote.jl`. The following features are all implemented in [`NonconvexUtils.jl`](https://github.com/JuliaNonconvex/NonconvexUtils.jl) and re-exported from `Nonconvex`. +## Table of contents + ```@contents Pages = ["user_defined.md", "other_ad.md", "chainrules_fd.md", "sparse.md", "symbolic.md", "implicit.md", "history.md"] Depth = 3 diff --git a/docs/src/problem/problem.md b/docs/src/problem/problem.md index 03f834e3..0215308b 100644 --- a/docs/src/problem/problem.md +++ b/docs/src/problem/problem.md @@ -5,6 +5,8 @@ There are 3 ways to define a model in Nonconvex.jl: 2. `DictModel` which assumes each variable has a name. The decision variables are stored in an `OrderedDict`, an ordered dictionary data structure. 3. Start from `JuMP.Model` and convert it to `DictModel`. This is convenient to make use of `JuMP`'s user-friendly macros for variable and linear expression, objective or constraint definitions. +## Table of contents + ```@contents Pages = ["model.md", "dict_model.md", "queries.md"] Depth = 3 From 65e5ac4021339f518254e34ed1e1d9883c13cb35 Mon Sep 17 00:00:00 2001 From: Mohamed Tarek Date: Sat, 18 Jun 2022 16:03:45 +1000 Subject: [PATCH 5/5] document abstractdiffy/forwarddiffy for a model --- docs/src/gradients/other_ad.md | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/docs/src/gradients/other_ad.md b/docs/src/gradients/other_ad.md index d4efa864..b359eb98 100644 --- a/docs/src/gradients/other_ad.md +++ b/docs/src/gradients/other_ad.md @@ -10,6 +10,8 @@ For more on how to construct a backend struct for each AD package, please refer to the README file of the [`AbstractDifferentiation`](https://github.com/JuliaDiff/AbstractDifferentiation.jl) repository. +## `abstractdiffy`ing a function + In order to use a specific `AbstractDifferentiation`-compatible AD package to differentiate a function `f(x...)` used in a `Nonconvex` objective/constraint, you can use the `abstractdiffy` function modifier from `Nonconvex`: ```julia F = abstractdiffy(f, backend, x...) @@ -42,3 +44,22 @@ which is short for: backend = AbstractDifferentiation.ForwardDiffBackend() F = abstractdiffy(f, backend, x...) ``` + +## `abstractdiffy`ing a model + +Instead of `abstractdiffy`ing or `forwarddiffy`ing one function at a time, the user can instead `abstractdiffy` or `forwarddiffy` an entire `Nonconvex` model including the objective, all the inequality constraint functions, all the equality constraint functions and all the semidefinite constraint functions. +```julia +ad_model = abstractdiffy(model, backend) +``` +where `model` is of type `Model` or `DictModel`. `ad_model` can now be optimized using any of the `Nonconvex` algorithms compatible with the model. Similarly, `forwarddiffy` can be used on an entire model: +```julia +fd_model = forwarddiffy(model) +``` + +By default, the objective and all the constraint functions will be modified with `abstractdiffy`/`forwarddiffy`. To prevent the modification of some component of the model, any of the following keyword arguments can be set to `false` (default is `true`): +- `objective = false` +- `ineq_constraints = false` +- `eq_constraints = false` +- `sd_constraints = false` + +Setting the `objective`, `ineq_constraints`, `eq_constraints`, and/or `sd_constraints` keyword arguments to `false` (default is `true`) will prevent the modification of the objective, all the inequality constraint functions, all the equality constraint functions, and/or all the semidefinite constraint functions respectively.