Explain bridges in the documentation (better)

[odow]

Since they're so complicated, I wonder if we need documentation in the style of literate programming where we explain in much more detail what's going on.

@matbesancon this blog post is a great start at explaining the bridges: https://matbesancon.github.io/post/2019-09-12-bridging-indicator/

Do you have any interest (or opposition) into adding something like it to the MOI documentation?

This is another one that could be included: https://matbesancon.github.io/post/2019-11-04-binary-julia/

(Suggestion from @glebbelov.)

[matbesancon]

@Wikunia also had some explanations on building bridges: https://opensourc.es/blog/constraint-solver-bridges/ https://opensourc.es/blog/generic-bridges/

[Wikunia]

I assume @dourouc05 would also be able to contribute here as he has 50+ bridges in https://github.com/dourouc05/ConstraintProgrammingExtensions.jl

[dourouc05]

I can probably do a PR for this tomorrow, if you're interested.

@Wikunia Closer to 70, right now :p! Even though that's a lot, most of these bridges are not really varied.

I would have a question about the best practices: when a bridge declares some constrained variable types (added_constrained_variable_types), should these types be repeated in added_constraint_types (SingleVariable-in-whatever)?

[dourouc05]

Here is the beginning of the tutorial: #1506. Unlike the blog posts that have been posted here, I tried to follow the principle of separating explanation of the concepts (manual) and the actual way of writing a bridge (tutorial).

[dourouc05]

Now that #1506 is merged, is anything else required for this issue?

[odow]

I'd like to keep this issue open. We still need to document the hyper graphs and bellman-ford algorithm etc.

[blegat]

I would have a question about the best practices: when a bridge declares some constrained variable types (added_constrained_variable_types), should these types be repeated in added_constraint_types (SingleVariable-in-whatever)?

No, add_constraint_types should only contain the type of constraints added with add_constraint, not those added with add_constrained_variable. Otherwise the bridge graph may not see possible bridging path and report unsupported constraints while they are feasible. Maybe this should be clarified in the doc.

[odow]

I've been making a bunch of improvements here:

• #1889
• #1881
• #1880
• #1878
• #1877
• #1876
• #1875
• #1874
• #1872
• #1870
• #1868
• #1869
• #1867
• #1865
• #1864
• #1863
• #1861
• #1860
• #1859
• #1850

[odow]

This is now in a much better state. Most of the bridge module is commented with docstrings. There is one glaring omission:

• https://github.com/jump-dev/MathOptInterface.jl/blob/master/src/Bridges/bridge_optimizer.jl

And in particular, the mechanism behind call_in_context, and how we do the substitution of variable bridges.

[odow]

We should update the documentation to reflect the new way of writing bridges with tests and final_touch

The recent constraint programming bridges are good examples to follow.