Energy Budget refactor (address deferred comments in PR #761)

Issue Type

Code Clean-up

Issue Description

There are a number of recommendations for PR #761 which were offloaded here due to a deadline for high priority coupled runs.

1) Update model documentation with description of new budget code and how to use. Much of this can be taken from the Changelog entry with updates from this issue and follow on PR.

2.) Calculation of area weighted averages - I thought this would be a useful feature to add to the history handler as it is present in some form in other components and would be useful for tracking a field during a model run just from the logfile. Global averages are calculated and stored but are only output to the log file for use with the energy budgets. a) recommend removing new pointer (wbuf) to areawts array and pulling weights as needed from the grid object or if caching is needed then moving that cache into the grid object.
b) Also instead of adding an area weights array just add sphere_area and use the existing areas to create area weights.

3.) Brian Eaton had some ideas for better addressing how to correctly account for subcycled fields. I would like to discuss this further. Brian commented: It seems that A averaging should be correct for tendencies outfld'd in subcycled code as long as those tendencies are computed using the correct time interval of the subcycle. If the tendency for a partial step is computed using the time interval of the full step, then it's actually a partial tendency.

I feel that the N averaging is adding too subtle a distinction to the time averaging operators. It also seems to be overloaded in cam_history to decided whether to set up area weights. My suggestion would be to compute tendencies using the appropriate substep size, or to create temporary storage so that partial tendencies can be accumulated and then outfld'd outside the subcycle loop.

4) I added a feature to the history handler to allow the creation of a composed field which is the mathematical sum or difference of 2 other defined fields. I don't know if this is useful enough to the general cam user or should be moved out of the cam history handler and into the budget module.

5.) Jesse and Cheryl raised make comments about the naming of budgets.

Budgets (and snapshots) have a descriptive name that is defined by the user as well as a derived shorthand alias which is constructed from its component snapshots. The budget module allows global budget integrals to be retrieved using either the descriptive name or the shorthand name. In a tendency budget, both snapshots are represented in the shorthand budget name. A shorthand snapshot name consist of two strings, one identifying the thermo_dynamic quantity and the second string is the location relative to a parameterization where the snapshot was taken. The kinetic energy tendency before and after dynamics would be given a descriptive name by the user ('dEdt_dynamics') and a shorthand name is constructed by the routine that would look like KE_dAF-KE_dBF. Jesse noted that the thermodynamic quantity is repeated and could be shortened. Cheryl noted that the code to keep and use two names for a field is confusing. I think we could drop the short name altogether and just refer to the budgets using the descriptive string. Currently Peter uses the shorthand naming when putting the budget log together.

6.) I need to reduce the output for the budget history tape. Peter only needs a small subset of the 2d fields written to the tape. During validation all thermo variables/snapshot combinations as well as budgets are currently written (over 400). Moving forward we really only need to account for total energy and water mass. Keep TE,WV,WL,WI and get rid of SE,KE,PO,MO,MR. We may add momentum back when they are ready to be analyzed.

7) If the addition of the feature to calculate and log global integrals to cam_history is OK then I will remove the overloaded dependency on 'N' to calculate and log those global averages and provide the user with the option of requesting that output on the history file and/or logging that info to atm.log. Any thoughts on how to allow the user to do that? I could add an optional flag to the addfld call to create an additional global average field on the history file. As for logging info to atm.in maybe a namelist variable to turn on logging for any global output? Or two optional flags to addfld one to put the history field out and one to log the global value? I could remove logging altogether but it does provide an easy way to check the field during a run without resorting to history.

8) Will update this issue as needed.

Will this change answers?

I Don't Know

Will you be implementing this yourself?

Yes

ESCOMP / CAM