Make the user-facing examples complete

[axch]

Currently, the examples that appear in the IPython notebooks in the examples directory are slightly misleading: Stepping through the notebook cell by cell does not actually run the simulations whose outputs the notebook plots. Rather, it writes the input files, but neither compiles or executes the MIM core, and instead draws plots from outputs that have been checked in to the repository.

This is undesirable because:

• The examples are incomplete as examples, in that if a user were to copy one to a new location, it wouldn't work.
• The auto-generated simulation outputs have to be kept checked in, which is bad.

Reasons I might imagine in favor of this arrangement:

• No need to mechanize source editing and recompilation of the MIM core in the examples, nor to scare users off with them. Fixing that is Issue #12; and it's not even unreasonable to own up to the ugliness in the meantime.
• Notebook runs faster because it skips the simulation.
  • But, I think the MIM core actually runs fast enough for this purpose. The function of immediately showing new users that the program works is served well enough by the notebooks containing the rendered plots in their cell outputs, and could also be out-sourced to a regular continuous-integration style build of high-resolution simulations (once we have examples we are confident enough in to show off that way).

It would also be a good idea to indicate that the examples require parameters.in files to exist, and maybe even give a sense of their content. One way to do that would be to execute cat parameters.in in the notebook (in the appropriate directory); but not too early, lest the user be chased off by the wall of output.

[edoddridge]

This is definitely a good idea.

As you say, the examples are not currently self-contained. This is an issue and regenerating appropriate inputs is a cumbersome and pointless maintenance burden.

I think we will still need to mechanise the compilation since the compiled Fortran binary won't be transferable across systems. Fixing #12 would remove the need for the rather ugly sed commands.

I agree that the examples run fast enough to have MIM execute them on the fly. If required we could alter the grid size or number of time steps. This may become a bigger issue as we develop a more complete set of examples that fully span the feature space.

Describing the examples properly, including their associated parameters.in files is something that I think should be done in the examples notebook(s).

[axch]

Yes, of course we will need to mechanize compilation, but with #12 done, it will only need to happen once, or at most once per notebook, not once per example :)

[edoddridge]

This issue was largely dealt with by #155, which implemented many of these ideas. Namely it:

• updated the examples to use the new syntax
• provided a single python script that could be run by the user to execute the examples
• automatically generated input files for the examples
• automatically generated plots of the output

157 Further refined this by checking in an animation of a longer example simulation, which takes ~20 minutes to run) and including it in the documentation.

While the documentation surrounding the examples should be expanded, the examples are now complete, self-contained, and can be executed by users with a straightforward command. I'm happy to close this issue and open a new ticket regarding enhancements of the examples documentation page.