Suggestions for documentation improvements

@BenLauwens

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

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

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

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:

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

I like the idea of visualizing the heat map.

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

More visual content in the docs would be welcome, I think.
This is a good example for flows in graphs: https://doc.sagemath.org/html/en/thematic_tutorials/linear_programming.html#flows

Another interesting idea from Sage docs: a compilation page "presenting commands roughly in the order a student would learn the corresponding mathematics" (but for LP not group theory, of course)
https://doc.sagemath.org/html/en/thematic_tutorials/group_theory.html

Some of these deserve a place in the docs: Sienna-Platform/PowerSimulations.jl#1218 (comment), possibly at performance tips

Update maxcut tutorial with https://github.com/blegat/LowRankOpt.jl?tab=readme-ov-file#example

Document how to drop down to MOI for some features: #4030

We should add tutorials and documentation for JuliaC/PackageCompiler. We may need to have a separate repo with tests so that they can be added to solver-tests.yml and extension-tests.yml.

So my conclusion from mucking about with PackageCompiler and JuliaC for the afternoon is that PackageCompiler just works. I'm hesitant to say we even need a tutorial.

You just need a package with a julia_main entry point:

MyApp/src/MyApp.jl

module MyApp
function julia_main()::Cint
    return 0
end
end

Then

import PackageCompiler
PackageCompiler.create_app("MyApp", "MyAppCompiled")

JuliaC, on the other hand,

Verifier error #139: unresolved call from statement (MathOptInterface.set)(JuMP.getfield(model::JuMP.Model, :moi_backend)::MathOptInterface.ModelLike, attr::MathOptInterface.ConstraintName, Base.getfield(cr::JuMP.ConstraintRef{JuMP.Model, MathOptInterface.ConstraintIndex{MathOptInterface.ScalarAffineFunction{Float64}, MathOptInterface.LessThan{Float64}}, JuMP.ScalarShape}, :index)::MathOptInterface.ConstraintIndex{MathOptInterface.ScalarAffineFunction{Float64}, MathOptInterface.LessThan{Float64}}, value::String)::Any
Stacktrace:
 [1] set(model::JuMP.Model, attr::MathOptInterface.ConstraintName, cr::JuMP.ConstraintRef{JuMP.Model, MathOptInterface.ConstraintIndex{MathOptInterface.ScalarAffineFunction{Float64}, MathOptInterface.LessThan{Float64}}, JuMP.ScalarShape}, value::String)
   @ JuMP ~/.julia/packages/JuMP/e83v9/src/optimizer_interface.jl:1294
 [2] set_name(con_ref::JuMP.ConstraintRef{JuMP.Model, MathOptInterface.ConstraintIndex{MathOptInterface.ScalarAffineFunction{Float64}, MathOptInterface.LessThan{Float64}}, JuMP.ScalarShape}, s::String)
   @ JuMP ~/.julia/packages/JuMP/e83v9/src/constraints.jl:423 [inlined]
 [3] add_constraint(model::JuMP.Model, con::JuMP.ScalarConstraint{JuMP.AffExpr, MathOptInterface.LessThan{Float64}}, name::String)
   @ JuMP ~/.julia/packages/JuMP/e83v9/src/constraints.jl:1053
 [4] macro expansion
   @ ~/.julia/packages/JuMP/e83v9/src/macros/@constraint.jl:173 [inlined]
 [5] macro expansion
   @ ~/.julia/packages/JuMP/e83v9/src/macros.jl:402 [inlined]
 [6] run_highs_example()
   @ MyCApp ~/git/jump-dev/ExampleJuMPProject/MyCApp/src/MyCApp.jl:35
 [7] main(ARGS::Vector{String})
   @ MyCApp ~/git/jump-dev/ExampleJuMPProject/MyCApp/src/MyCApp.jl:23
 [8] _main(argc::Int32, argv::Ptr{Ptr{Int8}})
   @ Main ~/.julia/packages/JuliaC/EFQEY/src/scripts/juliac-buildscript.jl:77

Verifier error #140: unresolved call from statement (MathOptInterface.set)(model::HiGHS.Optimizer, %new()::MathOptInterface.RawOptimizerAttribute, φ ()::Any)::Any
Stacktrace:
 [1] empty!(model::HiGHS.Optimizer)
   @ HiGHS ~/.julia/packages/HiGHS/yay5V/src/MOI_wrapper.jl:371
 [2] HiGHS.Optimizer()
   @ HiGHS ~/.julia/packages/HiGHS/yay5V/src/MOI_wrapper.jl:324
 [3] run_highs_example()
   @ MyCApp ~/git/jump-dev/ExampleJuMPProject/MyCApp/src/MyCApp.jl:32
 [4] main(ARGS::Vector{String})
   @ MyCApp ~/git/jump-dev/ExampleJuMPProject/MyCApp/src/MyCApp.jl:23
 [5] _main(argc::Int32, argv::Ptr{Ptr{Int8}})
   @ Main ~/.julia/packages/JuliaC/EFQEY/src/scripts/juliac-buildscript.jl:77

Has many many type stability issues all over the place.

Yes, even in direct mode, the fact that the type of the moi backend is non-concrete, which is needed for set_optimizer, makes it not possible to use with JuliaC. A possible solution would be to have a struct

struct ConcreteModel{T,M}
    moi_backend::M
    #...
end
const GenericModel{T} = ConcreteModel{T,MOI.ModelLike}
const Model = GenericModel{Float64}

Then, we could add a keyword argument like cement_backend in direct_model and Model. When set to true, it makes the backend unremoveable. But it would make JuliaC closer to possible, and it could also give small performance gains, since we avoid the type instabilities everytime we access the backend (so we could recommend it in the docs next to set_string_names_on_creation).

@Transurgeon

@Transurgeon suggested that we could use distance_to_set more liberally in the tutorials to convince people they may want to look at the quality of the returned solutions.

Navigation Menu

Repository navigation

Suggestions for documentation improvements #2348

General editing

Prior art

Resolved items

Improve current tutorials

Add new tutorials

Structuring larger models

Improved MIP modeling tricks

Parallelism

How to debug a JuMP model

Parametric problems

51 remaining items

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Suggestions for documentation improvements #2348

Description

General editing

Prior art

Resolved items

Improve current tutorials

Add new tutorials

Structuring larger models

Improved MIP modeling tricks

Parallelism

How to debug a JuMP model

Parametric problems

Activity

odow commented on Feb 3, 2022

odow commented on Feb 3, 2022

odow commented on Dec 7, 2022

odow commented on Jan 11, 2023

odow commented on Jan 26, 2023

odow commented on Feb 22, 2023

jd-foster commented on Feb 23, 2023

odow commented on Feb 23, 2023

blegat commented on Feb 27, 2023

odow commented on Feb 27, 2023

51 remaining items

Akshit222 commented on Oct 22, 2024

odow commented on Nov 26, 2024

jd-foster commented on Dec 16, 2024

jd-foster commented on Dec 16, 2024

joaquimg commented on Jan 28, 2025

odow commented on May 15, 2025

blegat commented on May 15, 2025

blegat commented on May 16, 2025

odow commented on Aug 21, 2025

odow commented on Aug 24, 2025

odow commented on Nov 20, 2025

franckgaga commented on Nov 27, 2025

odow commented on Jan 15, 2026

blegat commented on Jan 16, 2026

odow commented on Feb 2, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions