Add a structured list of solvers

[kellertuer]

This is a start to resolve #374.

I am still not so sure how to best to the list.

• for now there is a rough classification based on “knowledge” required about the cost
• each solver gets a 1-2 sentence items block for now and (maybe in a newline or even with a new subsubsection) an example call to the solver. Both the name and the function should be linked.

Further ideas welcome – for now I just build the groups and 3 examples for solvers how I would introduce them in “super-short”.

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 99.76%. Comparing base (462f8f0) to head (16bc3e0).

Additional details and impacted files

@@           Coverage Diff           @@
##           master     #380   +/-   ##
=======================================
  Coverage   99.76%   99.76%           
=======================================
  Files          73       73           
  Lines        7243     7243           
=======================================
  Hits         7226     7226           
  Misses         17       17           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[mateuszbaran]

• each solver gets a 1-2 sentence items block for now and (maybe in a newline or even with a new subsubsection) an example call to the solver. Both the name and the function should be linked.

I think we don't need an example call there, we can just link to an example that is available elsewhere. A couple of sentences about the solver is IMHO enough to provide an idea whether it's appropriate solver for a particular problems, and details should be elsewhere.

[kellertuer]

Ok, then without the call example.

[kellertuer]

I just finished the list. Currently, in every section, the algorithms are ordered alphabetically, we could order them also by “favourite ones first” in an oppinionated way.

I also kept an alphabetical table below, that now instead of name-function,state-“cost properties” has 3 columns name-function-state, where function refers to the high-level interface.

[mateuszbaran]

I just finished the list. Currently, in every section, the algorithms are ordered alphabetically, we could order them also by “favourite ones first” in an oppinionated way.

Maybe it would be sufficient to add a symbol that distinguishes algorithms known to be state-of-the-art for some problems (like quasi-Newton) and those that are here mostly for historical perspective and comparison (like gradient descent)? I don't think we can order algorithms from best to worst because that often depends on the problem being solved.

Anyway, I generally like the list and I think it's a very good addition 👍 .

[kellertuer]

Maybe it would be sufficient to add a symbol that distinguishes algorithms known to be state-of-the-art for some problems (like quasi-Newton) and those that are here mostly for historical perspective and comparison (like gradient descent)? I don't think we can order algorithms from best to worst because that often depends on the problem being solved.

For DocumenterInterlinks I saw that their docs that they handed out gold and silver medals for recommended (and follow up) methods/syntax. We could do that as well and explain that somewhere in the beginning. We could add also a symbol for merely academic/teaching examples as well, but phrase that carefully, I would like to avoid saying “This alsogirthm is not recommended”. The only ones I would maybe not really recommend are some of the full-matrix-updates in QN.

[mateuszbaran]

I see, maybe that's actually unnecessary.

[kellertuer]

I think it might be nice to add, I am just not sure how to decide which ones to mark with a symbol then.

[kellertuer]

I do like the current division into property based groups – I would like to think a bit about adding emojis to some of them to indicate certain recommendations (state-of-the-art, maybe something like fastest, or most used or so).