Decide if example should be written with global variables etc or with functions

[KristofferC]

Some examples and tutorial have the style of:

a = ...
b = ...

function do_something(a, b)
    ....
end

c = do_something(a,b)

Others have something like

function do_something(a, b)
    ....
end

function main()
    a = 
    b = 
    c = do_something(a, b)
end

The first way is a bit easier to write "prose style" of documentation for but the second style is more "julian" and might perform slightly better. It's also a little bit arbitrary in the first style which parts should be in global scope and which should be in local.

Would be good to be consistent I guess.

[KnutAM]

+1 for having more consistent style!

For the documentation, I find that the "prose style" works quite well and is better at conveying the message. It also makes it easier for users who run the code to inspect the created Ferrite objects, which is quite good for learning IMO. So I find that keeping most of those outside functions is a good choice in the introductory examples.

[termi-official]

I also think that the former is better, but we should put the information somewhere that it is recommended for users who write simulation drivers that the latter is the way to go.

[KristofferC]

The former is more awkward to work with though. For example if you want to @time it or profile it you need to include it from scratch but then you also time compilation time etc. It is also not really how we want anyone to write actual Ferrite code...

[KnutAM]

Maybe I'm often doing how one is not supposed to do then, but I assumed it is good/ok practice to create most objects at the top level, and run all computationally expensive stuff inside functions (i.e. typically all loops are in functions).

So I find that in the transient heat equation the time-stepping should really be moved to a function.

But on the other hand, the hyperelasticity tutorial is hard to "explore", since all objects are defined in solve(). If users wants to interact with the objects they must copy the code line by line. Then I'd rather have solve(dh, ch, cv, ...)

[fredrikekre]

It would make it easier to reuse parts of tutorials within the documentation if nothing was defined on top level and they were wrapped in module TutorialX etc. For example, you could then refer to Tutorial4.NeoHooke if you want to reuse that material in another example.

I think https://ferrite-fem.github.io/Ferrite.jl/dev/tutorials/stokes-flow/ is a pretty good middle ground perhaps? Compared to https://ferrite-fem.github.io/Ferrite.jl/dev/tutorials/hyperelasticity/ the main function is pretty short and if you want to explore you can evaluate the steps from this function pretty easily.

[termi-official]

I also often find myself in the situation of copy pasting the tutorial code around between tests and packages (https://github.com/Ferrite-FEM/FerriteViz.jl/tree/master/docs/src/ferrite-examples, https://github.com/Ferrite-FEM/Ferrite.jl/blob/master/test/integration/test_simple_scalar_convergence.jl). So I would appreciate if we can find an easier way to keep this stuff in sync.