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

Update Namelist documentation for all namelist options #940

Merged

Conversation

christinaholtNOAA
Copy link
Contributor

@christinaholtNOAA christinaholtNOAA commented Apr 26, 2024

Several UFS Apps use undocumented namelist settings in the UPP Read the Docs documentation. Specifically, I made these changes:

  • Added explanations for all namelist options used in the UPP code, and based the descriptions on the comments in the code where they were available.
  • The additions follow the documentation style of the ufs-weather-model namelist documentation. That means each entry is displayed in a table format, and information about type and default value is included.
  • I modified the style of the rst file to use long lines in paragraphs instead of wrapping, consistent with @gspetro-NOAA's documentation style preferences for supportability. Specifically, when diffs are proposed in PRs, GitHub's highlighting will draw the eye to exact differences made without concern for re-wrapping lines.
  • I updated the EMC URL because it failed during the docs build.

Fixes Issue #949

@WenMeng-NOAA WenMeng-NOAA added the documentation Improvements or additions to documentation label Apr 26, 2024
@WenMeng-NOAA
Copy link
Collaborator

@christinaholtNOAA Can you open a new UPP issue at here to link this PR?

@WenMeng-NOAA
Copy link
Collaborator

@christinaholtNOAA Can you sync your branch with the latest UPP develop?

@WenMeng-NOAA WenMeng-NOAA added the Ready for Review This PR is ready for code review. label Apr 30, 2024
@christinaholtNOAA
Copy link
Contributor Author

Sorry I am falling behind on your requests. I will open the ticket, apply the suggested changes, and update the branch by tomorrow. Thanks for guiding me through the process.

@christinaholtNOAA
Copy link
Contributor Author

@gspetro-NOAA, I am curious if you'd be okay with a standardized lowercase-only set of variables. Given that the capitalization strategy of these variables doesn't seem to have a rhyme or reason and that Fortran doesn't care, it seems like it might be more readable for users trying to get their namelists "right."

@gspetro-NOAA
Copy link
Collaborator

@christinaholtNOAA I think my main concern is just that the variables appear in the UPP code later in camel casing. I'm not sure what impact, if any, lowercasing things would have down the line. Lowercasing seems beneficial for uniformity and readability, but less expert users might be confused if later on they see camel-cased variables. So I can see plusses and minuses for both. @WenMeng-NOAA @FernandoAndrade-NOAA do you have any opinion?

@FernandoAndrade-NOAA
Copy link
Collaborator

@christinaholtNOAA I think my main concern is just that the variables appear in the UPP code later in camel casing. I'm not sure what impact, if any, lowercasing things would have down the line. Lowercasing seems beneficial for uniformity and readability, but less expert users might be confused if later on they see camel-cased variables. So I can see plusses and minuses for both. @WenMeng-NOAA @FernandoAndrade-NOAA do you have any opinion?

In the long run, I'd say uniformity and readability may be the bigger benefit than avoiding temporary confusion with users, even if I am partial to camel casing.

@christinaholtNOAA
Copy link
Contributor Author

@WenMeng-NOAA Do you have any thoughts here? It seems like we might be leaning for uniformity to go with lower case in the docs, if you're in agreement.

@WenMeng-NOAA
Copy link
Collaborator

@WenMeng-NOAA Do you have any thoughts here? It seems like we might be leaning for uniformity to go with lower case in the docs, if you're in agreement.

@christinaholtNOAA Fortran coding is case insensitive. From documentation uniformity and readability perspective, using lower case would be good.

@WenMeng-NOAA
Copy link
Collaborator

@gspetro-NOAA We will wrap up this PR for testing. Please let us know if you have more comments.

@WenMeng-NOAA
Copy link
Collaborator

@FernandoAndrade-NOAA Conducting the UPP RTs on either Hera or Orion would be sufficient.

@FernandoAndrade-NOAA FernandoAndrade-NOAA added the No Baseline Change No baseline of the UPP regression tests are made. label May 8, 2024
@FernandoAndrade-NOAA
Copy link
Collaborator

@FernandoAndrade-NOAA Conducting the UPP RTs on either Hera or Orion would be sufficient.

Hera RTs finished, this PR should be ready for merging.

@FernandoAndrade-NOAA FernandoAndrade-NOAA merged commit f7bc0cb into NOAA-EMC:develop May 8, 2024
5 checks passed
DavidHuber-NOAA added a commit to DavidHuber-NOAA/UPP that referenced this pull request Sep 9, 2024
* origin/develop:
  Updates to support MPAS applications (RRFS and HFIP) (NOAA-EMC#1029)
  Add 6-hrly max winds at 10m to SFS (NOAA-EMC#1019)
  Update jet.lua (NOAA-EMC#1027)
  Updates to support UPP use with MPAS (NOAA-EMC#1018)
  [develop]: Turn on WARN_AS_ERROR for Doxygen Documentation Builds (NOAA-EMC#1023)
  Sample PR for testing (NOAA-EMC#1007)
  Enable template 4-49 to obtain aerosol ensemble information (NOAA-EMC#1011)
  Relocate gfs/gefs/sfs control files (NOAA-EMC#990)
  update g2tmp on aws to 1.12.0 (NOAA-EMC#996)
  [develop]: Update requirements files (NOAA-EMC#994)
  Bump zipp from 3.17.0 to 3.19.1 in /doc/UserGuide (NOAA-EMC#991)
  remove stack-python load for Gaea build (NOAA-EMC#993)
  Bump certifi from 2024.2.2 to 2024.7.4 in /doc/UserGuide (NOAA-EMC#988)
  [develop]: Add Doxygen variable definitions to modules (NOAA-EMC#965)
  Read bucket either as an integer or float (NOAA-EMC#984)
  Update Orion module file for Rocky 9 upgrade (NOAA-EMC#987)
  UPP bugfixes for inline post and g2tmpl 1.12.0 compatibility (and number concentration updates) (NOAA-EMC#974)
  Sync the RRFS hotfix NOAA-EMC#967 and NOAA-EMC#968. (NOAA-EMC#979)
  Bump urllib3 from 2.2.1 to 2.2.2 in /doc/UserGuide (NOAA-EMC#981)
  Fix for hydrostatic runs - write out Omega and HGT from model output (NOAA-EMC#959)
  Bump requests from 2.31.0 to 2.32.0 in /doc/UserGuide (NOAA-EMC#963)
  Correct rt.sh paths (NOAA-EMC#957)
  Updates to use GRIB2 template 4.9 for QPFFFG and QPFARI variables in RRFS (NOAA-EMC#929)
  Add hourly averaged smoke PM2.5 and dust PM10 (NOAA-EMC#917)
  Update Namelist documentation for all namelist options (NOAA-EMC#940)
  update gtg code revision to v.4.16.3 (NOAA-EMC#954)
  Bump jinja2 from 3.1.3 to 3.1.4 in /doc/UserGuide (NOAA-EMC#953)
  Clean up labeling for 15-min accumulated fields (NOAA-EMC#948)
  Updates to the GSL exp1 ceiling diagnostic (NOAA-EMC#947)
  Additional RT log information (NOAA-EMC#941)
  add cmake load to modulefile/gaea.lua (NOAA-EMC#945)
  RRFS updates (NOAA-EMC#938)
  add module for AWS (NOAA-EMC#934)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation Improvements or additions to documentation No Baseline Change No baseline of the UPP regression tests are made. Ready for Review This PR is ready for code review.
Projects
None yet
Development

Successfully merging this pull request may close these issues.

4 participants