Add some documentation about the use of homotopy() for initialization

[Francesco Casella]

@AnHeuermann, I had an interesting discussion with a German master student who is using OpenModelica to demonstrate the feasiblity of using Modelica and OMC to simulate a sulphuric acid plant.

He was quite confused by all the parameters regarding homotopy, because the big picture is apparently not explained anywere. In fact, I'm also quite confused. It seems that the default is fixed-sted homotopy with four steps (i.e., three steps, see #5766). However, I understood we also have adaptive homotopy. Not sure how to activate it. Also, there are no references at all to the basic theory and to the solver used.

I would suggest that you add a paragraph to ​https://openmodelica.org/doc/OpenModelicaUsersGuide/latest/solving.html dedicated to homotopy-based initialization, where you can put a short summary of what homotopy-based initialization is all about, and then make a rational introduction to the used solvers, with some pointers to the relevant literature, and explaining how you can steer them with all the flags you introduced.

It would also be nice to add a short comment about the difference between homotopy-based initialization, using the homotopy() operator, and homotopy solvers for nonlinear algebraic loops in causalized systems. This may not be obvious to everybody.

Could you do that in time for the 1.16.0 release?

Thanks!

[Francesco Casella]

@AnHeuermann, this was incorrectly assigned to @lochel. Can you please give some feedback?

Thanks!

[Andreas Heuermann]

See PR 6675. But I could not see the result since my users guide don't want to build on my machine.

[Francesco Casella]

Thanks! See my comments on the PR

[Francesco Casella]

Retargeted to 1.17.0 after 1.16.0 release

[Andreas Heuermann]

I added more documentation in ​https://github.com/OpenModelica/OpenModelica/pull/6991

[Francesco Casella]

The documentation looks quite good now.