[docs] Add model kind and keywords in examples

[GermanHeim]

Documentation Issue
Examples do not have a model kind or keywords.

Suggested Improvement
It would be nice if we could add comments at the end of the description containing the model type and keywords, similar to how the GAMS model library does.

[odow]

Rigidly enforced model kinds box you into a corner.

What happens if you want to use Gurobi, and you have a QP objective, with some semi-continuous variables, and some nonlinear equality constraints?

https://www.youtube.com/watch?v=M31xoZGyj9w

[GermanHeim]

Hi @odow!

First of all, I just wanted to say that I really admire the work you and Miles have done with JuMP and SDDP! JuMP has been a huge source of inspiration while developing oximo, and I've learned a lot from reading its code and design.

Thank you for taking a look at oximo. I am reading all your comments on the issues, and they are all of great help.

Regarding this particular issue, when I started oximo, classifying models into "model kinds" felt like a natural design, especially since GAMS follows that approach. I later learned how JuMP/MOI handles this, and I came to think that its design is better.
This really became apparent when I started integrating SCIP, since SCIP can handle non-linear constraints (which would turn the model into an NLP), but not a non-linear objective function (although it can be reformulated).
This does not stop oximo from actually accepting NLPs from SCIP. SCIP would pass the model as an NLP, so oximo would continue until it found the objective function and error out there.

The Gurobi example you mentioned shows a similar issue. Right now, oximo would classify that model as an NLP, even though that isn't the most meaningful description/kind.

I do think the MOI approach is the better design, and I've been thinking about how to refactor oximo in that direction. I just haven't decided on the right design yet. It's been on my mind for a while, but I haven't had the chance to work on it yet because I've been prioritizing other features.

[odow]

I just haven't decided on the right design yet

There a bunch of things we got "wrong" with MOI: jump-dev/MathOptInterface.jl#2180

I'm not sure how the function-in-set stuff would go in Rust. Part of the reason it works so well in Julia is multiple dispatch.

[GermanHeim]

If I had to guess, it would probably be a bit more complicated in Rust.

Rust does not have Julia's multiple dispatch, but traits with generic parameters can provide a similar effect. A solver or model type can implement support for particular combinations of function and set types. The compiler can then select the correct implementation based on the solver, function, and set involved.
We would probably want unsupported combinations to fail at compile time.

I would probably do something like:
Macros (as is) -> typed function-in-set -> internal IR

The model would accept these typed constraints through generic traits and lower them into oximo's internal representation

Another option would be:
Macro (as is) -> typed function-in-set -> preserved function/set objects

This is probably closer to how MOI works.

Specialization could probably help with this, but it is unstable, and the Rust community is somewhat undecided about it.

[odow]

Yeah having an explicit list of functions and sets is okay. JuMP allows third-parties to define new functions and sets, but this shouldn't be a high priority.

It allows for nice extensions like https://github.com/jump-dev/MathOptLazy.jl, but the cost is that the space of functions and sets is unbounded and we can't use something like an Enum to represent the different types.