Clarification of GFS_Diagnostics.F90 metadata

gspetro-NOAA commented 4 months ago

Description

Currently, certain variables in GFS_Diagnostics.F90 have unclear descriptions/metadata. These variables are being documented in a table in the UFS WM User's Guide (via PR #2277) so that users and developers can easily reference the meaning of the diag_table variables they might like to add. This will help resolve UFS WM Issue #2032.

A few examples, especially related to smoke/aerosols:

GFS_Diagnostics.F90 describes emanoc as 'emission of anoc for thompson mp'. We need to know what "anoc" is or what the abbreviation stands for in order to provide clear documentation in the Weather Model User's Guide.
For emseas, the definition is 'emission of seas for smoke.' Is "seas" short for "seasalt"?
lu_nofire is defined as 'lu nofire pixes.' What does "lu" mean/stand for and what are "pixes"?
Similarly, lu_qfire is defined as 'lu qfire pixes.' What is qfire?

Other definitions seem to be wrong. For example, both xtts and xzts are defined as "NSST d(xt)/d(ts)," but it seems like xzts should be defined as "NSST d(xz)/d(ts)".

Overall, GFS_Diagnostics.F90 could benefit from explicit descriptions throughout. There are many other abbreviations in GFS_Diagnostics.F90 that we have clarified with developers and spelled out in the draft WM PR linked above. It would be helpful to incorporate these changes directly into the fv3atm code directly.

Solution

Spell out abbreviations and correct typos in GFS_Diagnostics.F90.

Alternatives

Open to ideas. Ultimately, it would be great to get this file and others into Doxygen so that documentation can be pulled directly from the code, but that would be a long-term goal.

Testing:

N/A. Issues in code metadata can be seen on examination. No run required.

Dependent PRs:

Directly reference any issues or PRs in this or other repositories that this is related to, and describe how they are related. Example:

required to support WM PR #2277
required to resolve WM Issue #2032

gspetro-NOAA commented 4 months ago

@haiqinli Do you happen to know what some of the smoke/aerosol variables (listed above) might be?

haiqinli commented 4 months ago

@gspetro-NOAA Sure, emanoc is the anthropogenic organic carbon emission; lu is land use; lu_* are arrays to keep track of different fire types, e.g. grass fires.

NOAA-EMC / fv3atm