Update high-level documentation

[dweindl]

Function-level documentation of AMICI is kind of fine. However, some higher level documentation seems to be missing. For example everything around Newton solver is rather hard to find unless one knows exactly what one is looking for. Similarly the concept of presimulation and others. Would be great to extend that. (Maybe during some documentathon?)

[dweindl]

Would be good to add some more detailed feature overview with links to relevant documentation/examples. And where missing, create documentation/examples.

[paulstapor]

Agree to 100%. Ideally, such a high-level doc involves:

• If not derivation, then at least explanation, of mathematical ideas behind (and why they are correct, or rather, why simpler realizations would be incorrect)
• An explanation of how sbml-import/pySB and ode-export are linked and intertwined. These routines are some thousand lines of code, which is really tricky and has functions/classes with really involved dependencies. Adding features to Amici which affect these routines is close to impossible without having an idea how things are inteded to work there.
• Many examples, which illustrate pitfalls (mathematically) and functionality.
• Some explananation in the sense of "how not to". Some code parts have been rewritten and optimized over and over again, because bad things happen, if certain stuff is nota accounted for. The whole symbolic processing with possibly exploding computation times is one aspect, implementation of conservation laws is another one (changes there are likely to cause failures in many other code parts).

[FFroehlich]

• An explanation of how sbml-import/pySB and ode-export are linked and intertwined. These routines are some thousand lines of code, which is really tricky and has functions/classes with really involved dependencies. Adding features to Amici which affect these routines is close to impossible without having an idea how things are inteded to work there.

The idea is that they are explicitly not intertwined but have public APIs that are used whenever possible to ensure modularity. This is also enacted within modules and should ideally also ensure that you don't have to worry about 95% of the code and don't need to understand all of it. This changes as soon as one wants to implement faster implementations for edge user-cases, as this usually explicitely involves circumventing general APIs.

High level docs have a very high chance of going stale, which makes them more confusing than helpful. Moreover, it's difficult to ensure they that they are located where people are looking for them. In terms of features the only sustainable way of documentation is in jupyter notebooks that are automatically run in CI to ensure they don't go stale. This should definitely extended beyond whats currently available. I also think a document laying out ground rules how things are organized and what general approach to follow when adding stuff is also definitely helpful and should be added. Beyond that, I think everything should go in the code as I find it highly unlikely that it will stay up to date otherwise.

[dweindl]

I think this can be closed.