Issue #49 - Add METplus instructions to the Jetstream2 tutorial

[Trumbore]

Pull Request Testing

• Describe testing already performed for these changes:
  
  Follow all instructions from scratch to ensure that they work correctly.

• Recommend testing for the reviewer(s) to perform, including the location of input datasets, and any additional instructions:
  
  Reviewer testing would be very time consuming due to the need to acquire a Jetstream allocation, and is not recommended.

• Do these changes include sufficient documentation updates, ensuring that no errors or warnings exist in the build of the documentation? [Yes or No]
  TBD after pull request is generated and the automated build reports any errors.

• Do these changes include sufficient testing updates? [Yes or No]

• Will this PR result in changes to the test suite? [Yes or No]
  
  If yes, describe the new output and/or changes to the existing output:
  
  No

• Please complete this pull request review by [Fill in date].
  

Pull Request Checklist

• Review the source issue metadata (required labels, projects, and milestone).
• Complete the PR definition above.
• Ensure the PR title matches the feature or bugfix branch name.
• Define the PR metadata, as permissions allow.
  Select: Reviewer(s)
  Select: Organization level software support Project or Repository level development cycle Project
  Select: Milestone as the version that will include these changes
• After submitting the PR, select Development issue with the original issue number.
• After the PR is approved, merge your changes. If permissions do not allow this, request that the reviewer do the merge.
• Close the linked issue and delete your feature or bugfix branch from GitHub.

[georgemccabe]

I recommend committing this run script to the i-wrf GitHub repository so it could be copied from there instead of downloading it. This would allow us to make any necessary updates to the script more easily and keep everything that is needed contained in the repo.

[georgemccabe]

Another benefit of committing it to GitHub is you can set the file permissions of the file in GitHub so you wouldn't need to open execute permissions by hand.

[Trumbore]

I like this idea. I hadn't been familiar with the contents of that repo, but see the structure now, and since it is already being pulled in this document, it would simplify things a lot. What do you think about also including the script to install Docker in that repo? Both would need to have names that accurately and fully define their scope.

[georgemccabe]

I hesitate to put a script in the GitHub repo that is very-specific to a single environment. This script wouldn't be used by users running on another machine besides Jetstream2, so I think it would be misleading to include it in the repo. We could poll the rest of the team to see what they think.

It looks like the script is relatively simple, so the commands could be included in the instructions instead of downloading and running a script from a short URL. This may appear more transparent to users.

I am going to be writing the "Getting Started" chapter of the I-WRF User's Guide. I was planning on including basic information on how to obtain the tools needed to run, e.g. Docker or Apptainer. I was going to include information relating to specific environments that we want to support, e.g. run module load apptainer on Casper/Derecho to load Apptainer. Your instructions to install Docker on Jetstream2 could be included in the "Getting Started" chapter since they are not specific to the Hurricane Matthew use case and a link from your instructions could point to the Getting Started section relating to Jetstream2. What do you think? If this sounds good, I can migrate your installation instructions to the Getting Started page when I create it.

[georgemccabe]

Isn't this namelist file in the i-wrf GitHub repository? Should it be obtained from there instead of downloading it?

[Trumbore]

Unfortunately, the file I am using is not quite the same as the one from GitHub. When using the GitHub version, I got parsing errors for the lines in the @time_control section that start with "io_form_". In the GitHub version, those lines all end with "= 2,", but that trailing comma causes problems in the test case so I had to create a version with it removed.

It's only a guess, but it may be because the run script I got from Bennett replaces some of the earlier @time_control settings with new ones. The GitHub version of lines like "start_year" have two values in them (i.e. "2016, 2019"). The overwritten versions only have one value (i.e. "2016,"). That change on 11 lines seems to be the only difference.

I don't know how else that namelist file is being used or if removing the trailing commas would break that other usage. Is the second column of date/time values actually needed in another usage? Maybe we should plan to have more than one of these configuration files so that demos with different needs can each store their files in GitHub.

Actually, a fair bit of the run script is spent tweaking the namelist file contents and it might be better to just save the tweaked version in GitHub and simplify the run script. I think that we should probably discuss these questions at a meeting before I make these changes.

[georgemccabe]

We could also discuss this with the group, but in my opinion we should include the namelist file that is used for the Hurricane Matthew use case in the GitHub repo and skip the logic in the run script that replaces values in it. Not only are there errors that are resulting in this, but it hides the details from the user who may review the namelist file we provide and become confused as to why the actual namelist file that is used to run WRF differs. We should provide a correct version of all of the configuration files that do not require any modification to run.

[georgemccabe]

I made a few changes to the docs and made a few in-line suggestions to provide all of the necessary scripts and config files via the I-WRF GitHub repo.

The rendered documentation with my edits can be viewed here: https://i-wrf--56.org.readthedocs.build/en/56/Users_Guide/matthewjetstream.html#matthewjetstream

Please address the suggested changes and re-request my review when you are ready. Other than those minor fixes, the content looks good to me.

[Trumbore]

This exercise has been updated, and additional files have been added to the repo, to minimize the amount of external files that must be downloaded during the exercise. All of the relevant files are now downloaded through a git clone and then copied to their destinations.

Both the namelist.input and the newly added namelist.wps files have been edited to match what the exercise requires, and the code in the run.sh script that previously modified the files has been removed. The resolves task #58.

Two data download steps have also been removed from the run script and moved into the exercise text, and the run script now only contains execution steps for running WRF, which seems cleaner. The run script was uploaded directly to the WRF folder, and not into a "scripts" sub-folder as was suggested in task #59. that task also suggested that METplus scripts could go into that folder, when they really should be under the parallel METplus folder, so there didn't seem to be an immediate need to create a scripts folder.

The new scripts, config files and instructions have been tested and work. Note that until the pull request is resolved, a tester would need to take an extra step immediately after cloning the repo: issue "cd i-wrf" and "git checkout jetstream-metplus" to activate this branch of the repo before attempting to copy the files from the repo.

While making these changes, it made sense to me to rearrange some of the content in the description to consolidate like subject matter. Very little new text was actually added.

Zilu has been added to this pull request so he can follow any discussion that ensues.