JuMP.jl
JuMP.jl copied to clipboard
jump-dev
Suggestions for documentation improvements
Hi there!
This issue is a catch-all for documentation improvement suggestions. I'll keep it updated with things to work on, rather than having lots of separate issues.
- If you have suggestions for things to add to the documentation, leave a comment below.
- If you're looking to contribute to JuMP, picking something off this list is a great place to start!
General editing
The easiest place to start is just to read through any portion of the docs and give it a good edit. Spelling, grammar, or edits for clarity are always good.
The easiest way to get started is to pick a Markdown page, e.g.,:
https://github.com/jump-dev/JuMP.jl/blob/master/docs/src/index.md
and then click the "Edit this file" pencil icon:
Make your changes, and then scroll to the bottom of the page for instructions on how to submit a pull request.
If you're not sure about a change, make it, open a pull request, and then we can discuss it.
Prior art
There are two existing sources of documentation that I would like us to work towards:
- The AMPL book https://ampl.com/resources/the-ampl-book/
- Mosek modeling cookbook https://docs.mosek.com/MOSEKPortfolioCookbook-a4paper.pdf
Resolved items
Resolved items
Improve current tutorials
A lot of the tutorials are quite basic and consist of just functions. We should revise the existing tutorials to show a wider range of interesting JuMP and Julia syntax and features.
I think it'd also help if each tutorial used a standardized template. Perhaps something like
# Title
This tutorial was contributed by XXX. It is based on the article/book/example of CITE.
## Goal
The goal of this tutorial is to demonstrate ...
## Setup
This tutorial requires the following packages
```Julia
using JuMP
import Foo
```
In addition, you need to data files [bar.txt] and [baz.json]. These files are contained in the JuMP repository
```
const _DATA_DIR = joinpath(@__DIR__, "data")
```
## Now start the tutorial
- [x] linear/knapsack
- [x] linear/multicommodity-flow
- [x] linear/workforce-schedulig
- [x] linear/steel-t3
- [x] nonlinear/qcp
- [x] nonlinear/rosenbrock
- [x] nonlinear/mle
- [x] nonlinear/clnlbeam
- [x] conic/kmeans
- [x] conic/correlation
- [x] conic/sdp-max-cut
- [x] conic/min-distortion
- [x] conic/robust-uncertainty
Add new tutorials
Structuring larger models
I wrote a nice answer here: https://discourse.julialang.org/t/integrating-mathoptinterface-into-an-industry-scale-project-e-g-constraint-management/71943/2?u=odow
Improved MIP modeling tricks
People consistently ask how to reformulate max and abs. These should be added. The Mosek modeling cookbook is the gold-standard for this: https://docs.mosek.com/modeling-cookbook/mio.html
Parallelism
I get this question quite frequently. A section should be added to the docs explaining the different options.
Links with content
- https://stackoverflow.com/questions/64177415/create-jump-model-with-multi-threading-in-julia
- https://discourse.julialang.org/t/parallel-solves-in-gurobi-jl/9908/8?u=odow
- https://discourse.julialang.org/t/improve-performance-of-a-code-with-very-large-of-garbage-collection/75548/20
How to debug a JuMP model
We need a getting started on debugging.
- The Julia debugger doesn't work well with JuMP.
- Update your packages to the latest version. JuMP will only support the LTS an the latest point release.
- Try a different solver
- Simplify the problem
- Comment out constraints until the infeasibility resolves itself
- Write tests.
@benlauwens has a great chapter on debugging: https://benlauwens.github.io/ThinkJulia.jl/latest/book.html#chap21. We should link to it, and re-phrase some of the suggestions in a JuMP context.
Parametric problems
The same user as #2662 asked for ways to solve a collection of problems over a set of parameters. We don't have a good way of doing this in JuMP (we have @NLparameter, but not @parameter), but it could be scripted using the modification API (or even just rebuilding the problem).
We should write a tutorial with the different approaches. Here's their suggestion:
I like the idea of visualizing the heat map.
- [x] @jd-lara asks: Add a tutorial on how to get the "duals" of a MIP (i.e., solve, fix the integers, convert to LP, and re-solve).
We had some code to do so in PowerSimulations (and gitter), but writing a nice tutorial would be good.
- [x] We should add in-place solves for the subproblems of the Benders decomposition tutorials #3145
- [x] #3250 add a tutorial (e.g., AC-OPF) using complex number support: https://github.com/jump-dev/JuMP.jl/issues/3114.
- [ ] add an introduction to optimization tutorial. See the discussion in https://github.com/jump-dev/JuMP.jl/issues/2859
I added a bunch of examples for constraint programming: https://jump.dev/JuMP.jl/dev/tutorials/linear/constraint_programming/
- [x] We should do the same for conic. A lot of those sets aren't used very much because they're not easily visible from JuMP.
We're at a point where I've done most of the documentation changes I wanted to do. We still need to add a tutorial/example on the complex-valued stuff, and potentially a general introduction to optimization.
I'm not sure if the JuMP docs are the right place for a general introduction. Does anyone have a list of teaching materials that we could steer people towards instead?
I think Linear Programming with MATLAB is brilliant and only wish (1) it was open and (2) it had a Julia version. But that doesn't answer your question.
- [x] #3238 Multiple people have been confused about setting warm starts for Ipopt because they follow the conic tutorial: - https://stackoverflow.com/questions/75543689/primal-and-dual-warm-starts-jump-error-message - https://discourse.julialang.org/t/jump-model-warm-start-using-ipopt/92660
- [x] #3250 quantum information, state discrimination suggested by @araujoms in https://discourse.julialang.org/t/error-when-constraining-variable-to-be-hermitian-psd/95223
https://github.com/jump-dev/JuMP.jl/pull/3250 would solve the quantum information and complex-number tutorials.
- [x] #3259 A tutorial playing with adding bridges, removing bridges and printing active bridges. Probably an examples with RootDet -> GeoMean -> (3 possible bridges for GeoMean) -> SCS would be good. It could be added at the end of https://jump.dev/JuMP.jl/stable/tutorials/conic/ellipse_approx/
- [x] Nested optimization problems seem to be coming up frequently. A tutorial on solving the inner problem, returning function and gradients and registering these? Already there are a few examples on discourse.
Nested optimization problems seem to be coming up frequently
We have https://jump.dev/JuMP.jl/stable/tutorials/nonlinear/user_defined_hessians/#Bilevel-optimization, but perhaps it needs to be it's own tutorial, rather than a section?
- [ ] This question comes up surprisingly often:
https://discourse.julialang.org/t/connecting-a-simple-first-order-solver-to-solve-standard-form-linear-program-to-jump/95694
I can see it being a good feature in Utilities, or as a tutorial with Simplex? It'd also make a good exercise for teaching.
We have https://jump.dev/JuMP.jl/stable/tutorials/nonlinear/user_defined_hessians/#Bilevel-optimization, but perhaps it needs to be it's own tutorial, rather than a section?
See #3274 . Might be too ruthless on Rosenbrock.
This question comes up surprisingly often:
https://discourse.julialang.org/t/connecting-a-simple-first-order-solver-to-solve-standard-form-linear-program-to-jump/95694
I can see it being a good feature in
Utilities, or as a tutorial with Simplex? It'd also make a good exercise for teaching.
I agree, I am also planning to convert this one into a JuMP tutorial https://github.com/blegat/SimpleConicADMM. This could even do SDP if we add scaled PSD back to MOI
So. I thought I'd give this Chat GPT thing a go. I could actually be useful in refining parts of the docs?(!?) Per their policies, I think we're okay to use the suggested text:
Oscar Dowson I'm writing technical documentation for JuMP, an algebraic modeling language for mathematical programming built in the Julia programing language.
Suggest an improvement to the following text:
[here I copied should_i_use.md]
The text provides a good overview of the key features of JuMP and the benefits of using it. Here are a few suggestions to improve the clarity and readability of the text:
Clarify the target audience: The text should clarify the target audience for JuMP. Who would benefit from using JuMP, and why? For example, is JuMP more suitable for researchers, students, or industry practitioners? Define mathematical programming: The text assumes that the reader is familiar with mathematical programming. It may be helpful to provide a brief definition or explanation of mathematical programming for readers who are not familiar with it. Expand on the constraints: The text mentions that JuMP can handle "a set of constraints", but does not provide any further details on what types of constraints JuMP can handle. It may be helpful to provide examples of the types of constraints that JuMP can handle. Provide more information on solver-independent interface: The text mentions that JuMP uses a solver-independent interface, but does not provide much detail on what this means or why it is important. It may be helpful to explain what a solver-independent interface is, and why it makes it easy to change between different optimization software packages. Clarify ease of embedding: The text mentions that JuMP is easy to embed in other workflows, but does not provide much detail on how this works. It may be helpful to provide examples of how JuMP can be embedded in different workflows, and why this is beneficial. Provide more information on MPL license: The text mentions that JuMP is MPL licensed, but does not provide much detail on what this means or why it is important. It may be helpful to explain what the MPL license is, and why it allows JuMP to be embedded in commercial software. Provide more information on advanced algorithmic techniques: The text mentions that JuMP provides access to advanced algorithmic techniques, but does not provide much detail on what these techniques are or why they are important. It may be helpful to provide examples of the types of techniques that JuMP supports, and why they are beneficial. Overall, the text provides a good starting point for describing JuMP's features and benefits, but could benefit from more detail and clarification in some areas.
Oscar Dowson Can you rewrite it for me?
Sure, here's a revised version of the text with the suggested improvements:
Should you use JuMP?
JuMP is an algebraic modeling language for mathematical optimization written in the Julia language. If you have a constrained optimization problem that can be formulated using the language of mathematical programming, JuMP may be a good fit for you.
When should you use JuMP?
JuMP is ideal for researchers, students, or industry practitioners who need to solve optimization problems that involve decision variables, a scalar- or vector-valued objective function, and a set of constraints. JuMP offers a number of benefits that make it an attractive choice for mathematical optimization:
User-friendly: JuMP's syntax mimics natural mathematical expressions, making it easier to write and understand optimization models. Solver independence: JuMP uses a solver-independent interface provided by the MathOptInterface package, which makes it easy to switch between open-source and commercial optimization software packages ("solvers"). Ease of embedding: JuMP is written purely in Julia and provides automatic installation of many open-source solvers. This makes it easy to embed JuMP in other workflows, such as simulations, web servers, or decomposition algorithms. JuMP's syntax is constrained by Julia's syntax and functionality, but this trade-off is offset by the ease of embedding. Speed: Benchmarking has shown that JuMP can create problems at similar speeds to special-purpose modeling languages such as AMPL. JuMP communicates with most solvers in memory, avoiding the need to write intermediary files. Access to advanced algorithmic techniques: JuMP supports efficient in-memory re-solves of linear programs and provides access to solver-independent and solver-dependent callbacks. These features provide access to advanced algorithmic techniques that were previously only available through solver-specific or low-level C++ libraries. When should you not use JuMP?
JuMP may not be the best fit for optimization problems that cannot be formulated as a mathematical program or problems that require specialized features that are not currently supported by JuMP or its solvers. If you need to use a specialized solver that is not currently supported by JuMP, you may need to look for a different optimization tool.
Overall, JuMP provides a powerful and flexible platform for solving mathematical optimization problems, and its user-friendly syntax, solver independence, ease of embedding, speed, and access to advanced algorithmic techniques make it an attractive choice for researchers, students, and industry practitioners alike.
I did something similar with index.md
Hi, thanks for all your work !
It seems that the nested optimization tutorial is no longer working : https://jump.dev/JuMP.jl/stable/tutorials/nonlinear/nested_problems/
If I copy-paste the full tutorial in Julia 1.8 (packages up-to-date), this line :
register(model, :V, 2, V, ∇V, ∇²V)
returns ERROR: Providing hessians for multivariate functions is not yet supported
EDIT
Also, I'm not sure that my understanding of the problem is good enough but, from the code, it seems that the first equation:
\begin{array}{r l}
\min\limits_{x,z} & x_1^2 + x_2^2 + z \\
s.t. & \begin{array}{r l}
z \textcolor{red}{\ge} \max\limits_{y} & x_1^2 y_1 + x_2^2 y_2 - x_1 y_1^4 - 2 x_2 y_2^4 \\
s.t. & (y_1 - 10)^2 + (y_2 - 10)^2 \le 25
\end{array} \\
& x \ge 0.
\end{array}
should be:
\begin{array}{r l}
\min\limits_{x,z} & x_1^2 + x_2^2 + z \\
s.t. & \begin{array}{r l}
z \textcolor{red}{=} \max\limits_{y} & x_1^2 y_1 + x_2^2 y_2 - x_1 y_1^4 - 2 x_2 y_2^4 \\
s.t. & (y_1 - 10)^2 + (y_2 - 10)^2 \le 25
\end{array} \\
& x \ge 0.
\end{array}
Hi @francis-gagnon, sorry for the delay. I didn't notice this notification.
It seems that the nested optimization tutorial is no longer working
That likely means you've installed an old version of JuMP. The docs are built and tested with every commit of JuMP, so things definitely work with the latest version.
Also, I'm not sure that my understanding of the problem is good enough but, from the code, it seems that the first equation:
Yes, you're correct. I'll make the change.
That likely means you've installed an old version of JuMP. The docs are built and tested with every commit of JuMP, so things definitely work with the latest version.
Yes, thanks for the response. I had EAGO.jl installed in my environment. It restricts JuMP to v.1.1.1, instead of v1.10.0.
Tutorial on using Dualization.dual_optimizer (e.g., close to https://jump.dev/JuMP.jl/dev/tutorials/conic/introduction/#How-to-choose-a-solver) and update conic tutorials to make sure they don't use pure standard conic form with geometric conic form solver or vice versa.
These uses SCS which is pure geometric conic form while the formulation is pure standard conic form so they should use a dualization layer:
- [ ] Luvász https://github.com/jump-dev/JuMP.jl/pull/3399/
- [ ] MaxCut as the formulation is pure standard conic form and SCS is geometric conic form: https://github.com/jump-dev/JuMP.jl/blob/87132630f78e0bb95aa78c2252e498f85758c400/docs/src/tutorials/conic/simple_examples.jl#L63-L70
- [ ] K-means https://github.com/jump-dev/JuMP.jl/blob/87132630f78e0bb95aa78c2252e498f85758c400/docs/src/tutorials/conic/simple_examples.jl#L138-L143
- [ ] Correlation https://github.com/jump-dev/JuMP.jl/blob/87132630f78e0bb95aa78c2252e498f85758c400/docs/src/tutorials/conic/simple_examples.jl#L187-L195
- [ ] Minimum distortion https://github.com/jump-dev/JuMP.jl/blob/87132630f78e0bb95aa78c2252e498f85758c400/docs/src/tutorials/conic/simple_examples.jl#L267-L281
- [ ] Quantum discrimination https://github.com/jump-dev/JuMP.jl/blob/87132630f78e0bb95aa78c2252e498f85758c400/docs/src/tutorials/conic/quantum_discrimination.jl#L69-L83, probably the other formulation as well if
Nis large enough
Add basic dualization comparison to simple examples (#3408) : closed, but revisit if we get any comments or questions on discourse.
@mlubin @jd-foster and I discussed a few documentation-related things at JuMP-dev. We could:
- Add a video walkthrough for each tutorial
- We could run each tutorial as a notebook with narration, like we would do in a tutorial
- We could record a short (60 sec) snippet pointing out the key features
- Develop course material for an introductory course in optimization
- Refine the current set of tutorials into a textbook
- We would need to resolve authorship and copyright questions
The GAMS summation thing came up again, so we definitely need better docs: https://discourse.julialang.org/t/creating-variables-from-a-vector-of-tuples-and-naming-them/103525
Semi-integer and semi-continuous variables under-appreciated. As a concept, these are not well known, and I keep seeing people recommend the binary reformulation. I wonder what we could do to make these more prominent in the documentation. #3562
Add section on function tracing https://discourse.julialang.org/t/jump-user-defined-functions-with-vector-inputs-and-outputs/106025 #3570
We should standardize the look of all plots in the documentation: https://github.com/jump-dev/JuMP.jl/pull/3569#issuecomment-1811814746
What do you think about switching to PlotlyJS for all the plots, get embedded interactivity, and drop the Plots dependency?