Improvement of Examples

[termi-official]

Hi everyone,

just to get everyone on the same page I want to shortly discuss the purpose of the examples in Ferrite and how to improve here.

In the current state example seem to have three primary purposes.

1. Showcasing functionality
2. Integration testing
3. Starting point for new users to derive their codes

While I like having the example (not wanting to diminish the developers efforts) I believe we should improve and standardize the examples to make them easier followable for new users.

My suggestion to improve the first point above is, that each and every example should...

1. start with a very short "What do learn here" section to summarize what the reader can expect to take away methodogically from the example
2. have hints about which ones of the other examples could be read to better understand of the current example, so we could keep advanced examples concise
3. provide sufficient mathematical theory (i.e. give and close all PDEs with the corresponding BCs and major points of the utilized discretization) to follow the implementation - currently some examples can be hard to follow (see e.g. incompressible_elasticity.jl example needs improvement #369 )

Regarding integration testing, maybe it can be useful to compute the examples with smaller meshes and time domains than the ones showcased? Currently the number of examples start to grow, but some of the examples already take quite some amount of time . 1:30 h is too much for such a small code.

[khorrami1]

Yes, I completely agree with you. For example, this example Ginzburg-Landau model needs to be clarified what the problem is and shows the equations and the corresponding PDE.