Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Clarification of the config example #172

Open
jwreep opened this issue Oct 10, 2024 · 4 comments
Open

Clarification of the config example #172

jwreep opened this issue Oct 10, 2024 · 4 comments

Comments

@jwreep
Copy link
Member

jwreep commented Oct 10, 2024

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.


Screenshot 2024-10-09 at 2 03 16 PM
@wtbarnes
Copy link
Member

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
Copy link
Member

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
Copy link
Member Author

jwreep commented Oct 17, 2024

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
Copy link
Member

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

2 participants