Clarification of the `config` example

[jwreep]

I'd like to suggest that the following snippet of the docs should be clarified a bit. It's not obvious to a few collaborators what the "clean" copy means, or how this relates to setting up simulations. I think the standard practice of most people who run HYDRAD is to make a copy of the directory for each simulation, but this isn't patently obvious to new users.

It would also be helpful to show an example where it points to a local copy, rather than just the download from Github.

---

[wtbarnes]

That's a good point. I can definitely see why this is confusing.

This is a semi-nonstandard usage and is mostly useful for running in a CI environment. We could just add a note in this example, but I wonder if it would be useful to add a separate section in the docs as well that gives a bit more background as to why things are done this way.

I wonder too if the function get_clean_hydrad should be renamed to something a little more informative. The usage of "clean" here implies that there are "dirty" HYDRADS as well! 😆

[wtbarnes]

Maybe having a how-to guide with the different options for configuring a simulation would be useful. This could include the following possible paths:

• Using your own local copy (without using get_clean_hydrad)
• Using your own local copy with get_clean_hydrad to remove the files that are not needed for running every simulation
• Using a copy automatically pulled from GitHub (i.e. the example shown in the docs above)

This guide could also include some basic rationale about when/why you would want to use each option as well as a little background as to what is actually happening in the configuration step.

[jwreep]

Yes, I think having explanations of a few different ways would certainly be helpful. There are also lots of options (numerics and physics), so a brief tutorial on changing things like radiative losses, or AMR options, etc., might also be useful. I think we've listed the variables in the docs, but a plot of, for example, the emissivity for different radiation options would really hammer home what they mean.

[wtbarnes]

I do not disagree though I would say this starts to stray into more of a user guide for HYDRAD itself. Ultimately, I do think it would be good to try and combine the existing user guide PDF with these docs (see #78).

Maybe a good place to start would be seeing how much of the tutorial you propose is covered in the user guide and then starting to slowly incorporate that into a dedicated section of these docs.