Documentation suggestions #2896
Description
@dourouc05 writes:
When reviewing some of Warren's code for CP-SAT in Julia, I noticed that https://jump.dev/MathOptInterface.jl/stable/manual/standard_form/ could be slightly more explicit about sets: they should not contain any reference to variables or constraints. This is quite clear in the reference (https://jump.dev/MathOptInterface.jl/stable/reference/standard_form/#MathOptInterface.AbstractSet), but not in the manual.
(He was implementing some constraint like LinMax, a maximum over a linear expression, with the result in a variable index. CP-SAT has an explicit target in the constraint representation, which is not how MOI works.)
In my opinion, the missing part here is that sets are totally independent from the instance, even when instantiated: a LessThan(4) will remain a LessThan(4) in someone else's code, even though the model is very likely to be quite different. This would have helped avoiding this mistake (and it's not as clear in the paper). Having the same information distilled at several places in different ways would make it easier for people to understand this subtelty.
I was thinking of adding something like this just before the tip at the top of https://jump.dev/MathOptInterface.jl/stable/manual/standard_form/:
The sets are abstract and instance-independent, while the functions encode the relationship to the variables. Sets relate to the problem structure while functions make the problem concrete.
I'm not sure the formulation is the best one (otherwise, I would have made a CL directly). What do you think?
Also, the tutorials might be missing a page about adding new constraints to MOI. Or maybe I just missed it :)! If you think it'd be helpful, I can contribute a draft.