Suggestions for documentation improvements

[odow]

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

• linear/knapsack
• linear/multicommodity-flow
• linear/workforce-schedulig
• linear/steel-t3
• nonlinear/qcp
• nonlinear/rosenbrock
• nonlinear/mle
• nonlinear/clnlbeam
• conic/kmeans
• conic/correlation
• conic/sdp-max-cut
• conic/min-distortion
• 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.

0. The Julia debugger doesn't work well with JuMP.
1. Update your packages to the latest version. JuMP will only support the LTS an the latest point release.
2. Try a different solver
3. Simplify the problem
4. Comment out constraints until the infeasibility resolves itself
5. 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:

![image](https://user-images.githubusercontent.com/8177701/129110774-cc2688d9-ac27-40e2-b6b0-390e1d7c2e0a.png)

I like the idea of visualizing the heat map.

[odow]

• add an introduction to optimization tutorial. See the discussion in [docs] Add a "Getting Started with optimization" tutorial #2859

[odow]

@blegat suggests adding an example using a third-party AD package: #3577 (comment)

[blegat]

We could write plotlyjs() to have a the plotly backend but I would stay with the Plots interface. Most people know this interface and now the plotly one

[odow]

We could add an MPC tutorial: jump-dev/JuMPTutorials.jl#49

[odow]

We need to add some "transitioning from XXX" tutorials.

We keep getting questions from AMPL/GAMS/MATLAB users.

See this interesting discussion:
https://discourse.julialang.org/t/nonlinear-optimization-with-many-constraints-autodifferentiation-which-julia-solution/110678

[blegat]

I've had a request for a tutorial for getting the matrix form, e.g., doing this:

cache = SCS.OptimizerCache{Int}()
MOI.copy_to(cache, backend(model).optimizer.model.model_cache)
A = convert(SparseMatrixCSC{Float64,Int}, cache.constraints.coefficients)
b = cache.constraints.constants.b

[jd-foster]

With the new Transitioning section, it would be good to have a short referring section from the "Should you use JuMP?" page
Also, I should write a "Transitioning from GAMS" one.

[odow]

What do you think about switching to PlotlyJS for all the plots

I forgot to mention, I took a look at this. But I couldn't get Documenter to render the interactive plots, and something was weird with the PDFs. Sticking with Plots.jl and the defaults for now seems okay.

[jd-foster]

#3729 (comment) should be a page in the docs.

[blegat]

Agreed, maybe it should mention @profview_allocs as well (by the way, I find this macro suprisingly difficult to find by googling, it should be advertised)

[odow]

We could add feasibility cuts to the Benders tutorial

x-ref https://discourse.julialang.org/t/dual-ray-from-lp-solved-by-dual-algorithm/114068/4?u=odow

[joaquimg]

I'd say that should be either a second part of the tutorial or even a separate tutorial.
Adding all of it might make the simple Benders unnecessarily complex.

[blegat]

We can actually also add unbounded cuts (it's in https://github.com/JuliaStochOpt/StructDualDynProg.jl/blob/de7801fc990743f326b7c0f09a3b41d48feb0d8d/src/StructProg/nlds.jl#L55-L57). The idea is as follows: if the parent is unbounded, you compute the unbounded ray. Then you solved modified children by adding a variable λ and using λ * parent_ray instead of parent_solution. Then the generated cuts will cut out the ray, then you can add these are cuts to the parents and it will hopefully become bounded. I needed for an example but I always wondered if anyone had the same need and how it was handled if not like that.

[odow]

I always wondered if anyone had the same need and how it was handled if not like that

We add a big-M a priori bound to the θ variable so that the parent problem is bounded 😄