bgrid_solo scripting and documentation update

[mjs2369]

Description:

• Updates the script workshop_setup.sh to include additional steps that are necessary for it to run successfully: cp perfect_output.nc filter_input.nc and setting
&filter_nml
perturb_from_single_instance to .true. in input.nml
• Updates the documentation for the bgrid_solo model to include a list of steps to build and run filter manually (the same steps executed in workshop_setup.sh). This makes the process more transparent to the user and should also make it easier for our users to know which input files they need and how they are being used.
• Removes the unnecessary file bgrid_solo/work/filter_input.cdl.REMOVED.git-id

Fixes issue

fixes #647

Types of changes

• [x] Bug fix (non-breaking change which fixes an issue)
• [ ] New feature (non-breaking change which adds functionality)
• [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
• [x] Documentation update

Documentation changes needed?

• [x] My change requires a change to the documentation.
  • [x] I have updated the documentation accordingly.

Tests

• Compiled and ran bgrid_solo model, both with and without the use of workshop_setup.sh
• Manually built the documentation

Checklist for merging

• [ ] Updated changelog entry
• [x] Documentation updated
• [ ] Update conf.py

Checklist for release

• [ ] Merge into main
• [ ] Create release from the main branch with appropriate tag
• [ ] Delete feature-branch

Testing Datasets

• [ ] Dataset needed for testing available upon request
• [ ] Dataset download instructions included
• [x] No dataset needed

[nancycollins]

i'm sorry if i missed this discussion, but we had originally not put netcdf files into the repo, partly because they're binary and can't be easily diff'd to see differences. instead we distributed the input for perfect model and filter as text .cdl files. the standard netcdf utility 'ncgen' used to be run in the workshop setup script to generate the .nc files at run time. was there a decision that this wasn't a good option?

edit to add: there is still both a perfect_input.cdl as well as a perfect_input.nc in the bgrid_solo dir. i think running filter from a single ensemble member is a smart choice - did the old filter_input.cdl have something like 20 members so it was too big?

[hkershaw-brown]

edit to add: there is still both a perfect_input.cdl as well as a perfect_input.nc in the bgrid_solo dir. i think running filter from a single ensemble member is a smart choice - did the old filter_input.cdl have something like 20 members so it was too big?

Its unclear what the decisions where:

The file in the repo appears to be a SHA (maybe for svn, doesn't seem to match DART or DART_development models/bgrid_solo/work/filter_input.cdl.REMOVED.git-id

The history is not helpful either https://github.com/NCAR/DART/commits/main/models/bgrid_solo/work/filter_input.cdl.REMOVED.git-id

and why this change was committed as part of 7aac084 - can't tell what the goal was here either.

the workshop_setup.sh{csh} hasn't worked for 7+ years. Recently someone https://github.com/NCAR/DART/issues/647 was trying to use bgrid_solo and was understandably confused what the file filter_input.cdl.REMOVED.git-id was. Time to get rid of it, and fix the workshop_setup script.

[nancycollins]

i think some of the breakage happened when quickbuild was changed (and improved). the original older quickbuild used to look for .cdl files and run ncgen on the to make a .nc file on demand. then the workshop_setup scripts didn't have to do anything and they ran. i assume the new quickbuild doesn't do that anymore. it seems the choices are to remove the .cdl files from the repo (they exist in many of the lower order models) and commit the corresponding .nc files, or see if the quickbuild could generate .nc files on demand if a .cdl file exists.

[hkershaw-brown]

i think some of the breakage happened when quickbuild was changed (and improved). the original older quickbuild used to look for .cdl files and run ncgen on the to make a .nc file on demand. then the workshop_setup scripts didn't have to do anything and they ran. i assume the new quickbuild doesn't do that anymore. it seems the choices are to remove the .cdl files from the repo (they exist in many of the lower order models) and commit the corresponding .nc files, or see if the quickbuild could generate .nc files on demand if a .cdl file exists.

the new quickbuild.sh runs ncgen. The brid_solo workshop script has not had a filter_input.cdl for 7+ years. bgrid_solo workshop_setup.csh did not work pre the new quickbuild.sh

[nancycollins]

never mind any of my previous comments. i was completely confused about things.

[kdraeder]

Is workshop_setup.sh in work because it runs quickbuild.sh? To me it seems more consistent with the directory structure and naming to put it in shell_scripts and edit it to refer to ../work/... as needed, and maybe run the OSSE in ../test.

[nancycollins]

i'm not sure about the bgrid_solo model, but workshop_setup.sh was in the work directory for some of the lorenz models because the tutorial used it to build and run pmo and filter so users could run the diagnostics right away. this whole script may have outlived its usefulness.

[kdraeder]

i'm not sure about the bgrid_solo model, but workshop_setup.sh was in the work directory for some of the lorenz models because the tutorial used it to build and run pmo and filter so users could run the diagnostics right away. this whole script may have outlived its usefulness.

Thanks for the context! I can see how it's simpler in the context of a workshop to do all the steps in one directory, since there's limited output and number of steps.
This could be an opportunity to avoid the common development path of taking whatever special purpose code exists and generalizing it just enough for the next goal, while declining to purge "baggage" code if it's not in the way. Or maybe this is too entrenched by now.

[mjs2369]

i'm not sure about the bgrid_solo model, but workshop_setup.sh was in the work directory for some of the lorenz models because the tutorial used it to build and run pmo and filter so users could run the diagnostics right away. this whole script may have outlived its usefulness.

@hkershaw-brown @nancycollins @kdraeder

Are we thinking we remove workshop_setup.sh all together then and update the docs accordingly? Or should we keep it in the repo?

[mjs2369]

Update: removing the workshop_setup script from the repo and updating the docs accordingly.

[kdraeder]

I pulled the latest version and read through the readme.rst. Here are my top items or questions. Namelist:

There's no directory INPUT or template {atmos_model,?}.res file. I see several options; 1) remove the reference to INPUT, 2) note the absence (and that it's "never" used?) 3) add an option to the 'resolution' paragraph about getting resolution from running the model from a cold start, using the resolution variables in the model's namelist, and finding atmos_model.res in directory RESTART.

INPUT/atmos_model.res is hard-wired in fms_src/atmos_solo/atmos_model.f90. I also see that bgrid_prog_var.res is hard-wired in fms_src/atmos_bgrid/tools/bgrid_prog_var.f90. Should all of the atmos_bgrid (spectral dynamical core?) be ignored because DART uses only atmos_solo?

Inconsistent formatting for programs and files; item in the main text italicized in the template file no formatting in the other namelist entries

I have not worked through the test steps (an excellent addition!), but I will if that would be helpful.

I also have a readme.rst with some typo fixes and suggested formatting. After we've answered my questions about model resolution, I could add in text about that and push my version for review.