search

jump-dev / JuMP.jl

Modeling language for Mathematical Optimization (linear, mixed-integer, conic, semidefinite, nonlinear)
http://jump.dev/JuMP.jl/
Other
2.24k stars 397 forks source link

[docs] Add a "Getting Started with optimization" tutorial #2859

Closed jd-foster closed 1 year ago

jd-foster commented 2 years ago

Would you accept a PR for the following?: a page in the docs in the Tutorial section called "Getting Started with optimization" that gives an overview of the math. formulation of linear, conic, quadratic and nonlinear programs? At the moment, the descriptions are scattered between each subsection, and may be hard for a learner to fit their problem type into the right category. An extension to this would be a "decision tree" format to help direct classification.

jd-foster commented 2 years ago

Just realised I should probably have just added this under #2348 ...

odow commented 2 years ago

Yeah I've been thinking along these lines. (It's why I added the various introductions.)

We currently have a mix of:

Summarizing all of this into a single "getting started" tutorial to help people identify what types of problems JuMP can solve, and what type of problem they have/what solver they should be looking for would be useful.

I wondered about going for some of the early AMPL chapters, like "what is a decision variable/objective/constraint", but we need to decide what should go in the JuMP documentation and what should be left out.

If https://jump.dev/JuMP.jl/dev/JuMP.pdf is to become "JuMP, the book" at some point, I think we need an intro to modelling/optimization chapter covering this sort of stuff, even if only briefly.

Just realised I should probably have just added this under

I think this deserves a separate issue. It's probably the next biggest issue that new users face with the tutorials.

jd-foster commented 2 years ago

I wondered about going for some of the early AMPL chapters, like "what is a decision variable/objective/constraint", but we need to decide what should go in the JuMP documentation and what should be left out.

I've read the AMPL book extensively, and I like how it's very example+language driven in its approach. I can see the scope creep for this proposal, but the primary purpose would be to let the reader 'fall through' the problem types and identify the most specific type of program that covers their formulation. There is a whole separate issue of teaching how to identify and perform re-formulation.

odow commented 2 years ago

One thing that always surprises me about the AMPL book (or at least the 2nd edition that I have) is that it is primarily LP. It's not until Chapter 18 that we get nonlinear, Chapter 19 introduces complementarity problems (!), and then Chapter 20 introduces integer problems.

I can see the scope creep for this proposal

Yes. But having said that, great introductory material will only help more people use JuMP and make it easier to teach in classes.

jd-foster commented 2 years ago

I've put an initial intro down here.

I would appreciate initial comments on whether this is hitting the right tone and reader level we're aiming for. The wording is still quite rough.

odow commented 2 years ago

The introduction in Jorge's Numerical Optimization book is quite good. The gist is:

My guess is that the best way forward is to open a PR, but it's probably going to take quite a lot of work-shopping to get right.

odow commented 1 year ago

Since we haven't made progress on this, I'm going to close in favor of the generic #2348. We do have to be careful about the scope of the JuMP documentation. It's not a textbook for LP101.

jd-foster commented 1 year ago

Sounds good. I think priority should be given to readable tutorials that embed most content.