escomp/atmospheric_physics

CCPP-enabled Atmospheric Physics

IMPORTANT NOTE - This repository is currently under development and items contained within it should be used with caution.

NCAR CCPP-enabled Atmospheric Physics

Physics packages which are CCPP_enabled (along with supporting routines) are stored in this repository.

Requirements for ccpp physics schemes

• Physics schemes contain two files, a .F90 file which contains the routines and a .meta file which contains the CCPP metadata.

• Standard names for metadata can be found here

• Physics modules may contain one or more of the following routines (where XXX is the name of the module containing the physics)

  • XXX_init - contains the startup/restart initialization required for the package. This is unthreaded and may contain I/O of undistibuted data (e.g. parameter tables)
  • XXX_timestep_init - contains the initialization required for each timestep. This is unthreaded and may contain I/O of undistibuted data (e.g. parameter tables)
  • XXX_run - the code which is run every timestep. Threading is controlled via the host model and the number of available threads will be passed into the routine. No I/O is permitted in this routine
  • XXX_timestep_final - contains any post timestep handling. This is unthreaded
  • XXX_final - contains any code logic which needs to be performed at the end of the run prior to the program exiting. This is unthreaded.

Steps to adding a physics package to the repository

• Currently under discussion

CCPP resources

• ccpp framework repository

atmospheric_physics's Issues

Update MICM wrapper for species unit conversions

Convert from CAM-SIMA units for species concentrations (kg kg-1) (mass of species / mass of dry air)

Acceptance Criteria
During "run" function, MICM wrapper converts all species to mol m-3 by:
mmr_species * dry_air_density / MW_species
prior to solving, and then converts back to mass mixing ratio after solving

Ideas
Add dry air density as input argument to run function (already available through CCPP)
Molecular weights (kg mol-1) are available in constituents object
Add the following line to https://github.com/ESCOMP/atmospheric_physics/blob/main/suite_musica.xml:

<scheme>calc_dry_air_ideal_gas_density</scheme>

Metadata is in old format

The CCPP Framework has a new metadata table standard that includes a table properties section. The metadata in this repository should be updated to that standard.

wet-to-dry conversion not CCPP compliant

The routines, wet_to_dry_run and dry_to_wet_run are not CCPP compliant because they use the same variable (and
therefore same standard name) for both the wet and the dry state.

In addition, these routines use optional arguments which are not supported by the CCPP Framework.

The output variables of these routines need to be separate from the associated input state variable.

To avoid the use of optional arguments, separate routines need to be provided for water vapor and standard water species. In addition, to allow conversion of other constituents and groups of constituents, a routine that takes an array of constituents as input should be provided. One issue here is how to define the input and output arrays. Currently, we do not have a naming scheme for a constituent array that would distinguish 'dry' from 'wet' (or 'moist', are we even going to support 'moist'?†) and there will always elements of these arrays which are not convertible between 'wet' and 'dry'.

One possibility is to try and use the framework to generate code to keep track of the state of variables inside a constituent array. A companion constituent property array could be required that would keep track of the state of each of the variables, however, there is no easy way to track variables which are separate indices into the constituent array. Ideas?

† In CAM, we determine 'wet' via a namelist variable specifying the water species which participate in the 'wet air mass'. However, the CCPP standard name rules distinguished between _wrt_moist_air and _wrt_total_mass (see rule 5). My inclination is to go with _wrt_total_mass as that is how we will usually use the variables. Thoughts?

Suite name needs to match file name in CCPP SDFs

The current CAMDEN infrastructure requires that an SDF file name matches the style of suite_<name>.xml, where <name> is the name of the physics suite as listed in the name attribute in the SDF file itself.

However, for both suite_kessler.xml and suite_held_suarez_1994.xml the file name and suite name are mismatched, which will cause CAMDEN to fail. Thus the suite name should be updated in those two files to match the file names.

Along with that change, this SDF naming rule should be added to this repo's wiki so that future developers know of this requirement ahead of time.

Bring over cldfrc_fice, qsat and qsat_water to be CCPP'ized

We will explore bringing over just the routines that ZM is "use"ing and not the entire module

Need tendency update utility routines

To alleviate the need for specialized state-update routines for each converted scheme, create a set of apply_tendency_of_<x> routines which apply a specific tendency to its corresponding state variable(s).

Update MUSICA git tag

Update MUSICA git tag from main to specific commit (temporary)

Update height grid in TUV-x before calculating rate constants

Update the height grid's mid points and edges in TUV-x for each column prior to calculating photolysis rate constants.

Acceptance Criteria

• TUV-x photolysis rate constants are calculated for the actual heights for each column at each timestep
• The mapping of TUV-x height midpoints and edges to CCPP height variables is documented

Ideas

• Identify the CCPP standard names for layer mid-point and interface heights
• Follow the logic of the TUV-x PR into CAM: https://github.com/ESCOMP/CAM/blob/c12d1e46e0fdc1dccb0a651a6c9fefd6bb80b2ba/src/chemistry/mozart/mo_tuvx.F90#L1329-L1388

Update temperatures in TUV-x before calculating rate constants

Update the temperatures profile edges in TUV-x for each column prior to calculating rate constants.

Acceptance Criteria

• TUV-x photolysis rate constants are calculated for the actual temperatures for each grid cell at each timestep

Ideas

• Identify the CCPP standard name for temperature at layers/interfaces
• Map the temperatures to the TUV-x height grid
• Follow the logic of the TUV-x PR into CAM: https://github.com/ESCOMP/CAM/blob/c12d1e46e0fdc1dccb0a651a6c9fefd6bb80b2ba/src/chemistry/mozart/mo_tuvx.F90#L1391-L1413

Issues with ordering of loops for Kessler

A brief conversation with Brian Eaton indicated that there are issues with the ordering of some of the loops in kessler. More details will be added once we have had an in-person discussion.

dry air density is not at STP

The dry air density variables used in the state_converters and kessler physics schemes have standard names that imply they are at Standard temperature and Pressure (STP). However, that density quantity is a function of the atmospheric temperature and pressure, which means it is not in fact at STP. Thus this label should be removed in order to avoid a name collision with density variables that are in fact at STP.

Create suite for AOA

Variables "z" and "zm" are geopotential height (at mid-levels), not geopotential

In the Kessler.meta and geopotential_t.meta files, the variables z and zm should be the geopotential height at mid-levels. However, their standard names have them labeled "geopotential", which is a different physical quantity.

These standard names should thus be modified to state "geopotential height", not just "geopotential". Otherwise there is a high risk that a future user or developer will use these variables in an incorrect way.

Add CCPP update of dadadj

Refactor dadadj to use CCPP and add to this repository. Will follow the Procedure for converting a CAM parameterization to CCPP as a guide.

Cannot build Kessler CCPP cap using "feature/capgen" ccpp-framework branch.

When using the "feature/capgen" branch of the ccpp-framework to try and generate a CCPP cap with the Kessler suite, the generation fails with the following error:

parse_source.ParseInternalError: Attempt to set intent of temp, at /glade/work/nusbaume/SE_projects/new_cam_sandbox/CAMDEN/src/physics/ncar_ccpp/state_converters.meta:18 to in, only 'inout' allowed.
intent source: temp, at /glade/work/nusbaume/SE_projects/new_cam_sandbox/CAMDEN/src/physics/ncar_ccpp/kessler_update.meta:76

This occurs both when trying to build CAMDEN with the Kessler suite, and when trying to run the capgen script (ccpp_capgen.py) independently. The original "CPF_0.2.016" tag used in CAMDEN was able to generate the caps without an issue, so something must have changed on the ccpp-framework side to cause this problem.

Finally, I should note that even though I am posting this in atmospheric_physics, it is unclear to me if this is actually a problem with the current CCPP-ized physics routines, or if it is a bug in the feature/capgen branch of the ccpp-framework. However, given that I can't just walk down the hall and ask, this seemed like as reasonable a place as any to bring it up.

Any thoughts or ideas would certainly be appreciated!

Need to add CCPP physics suite for CAM's dry adiabatic adjustment parameterization

The dry adiabatic adjustment physics parameterization in CAM (dadadj) needs to be CCPP-ized, and the resulting physics suite code should be added to this repo.

Need CCPP scheme description metadata

As CCPP-ized physics and chemistry schemes are shared amongst host models, it may become important to include additional metadata somewhere in the scheme comments that can help users know the current development state and provenance of the scheme itself. So far we have come up with the following list of information that would be good to have for each scheme, if possible:

• The institution/lab that provided the scheme.
• A scheme reference URL (e.g. a DOI to a paper, or a URL to website documentation).
• A scheme description summary (e.g. a few sentences on what the scheme is doing and/or what is for).
• The last modification date.
• Contact person (e.g. name and email).

This is in no way an exhaustive list, and we can always separate "mandatory" versus "encouraged" metadata. If anyone has additional description metadata they would like to add, or have strong feelings on what should be required versus just recommended, then please feel free to add a comment here.

Hopefully this issue will be closed once all of the schemes that currently exist in this repo have been updated with at least the minimum set of description metadata that folks have decided should be mandatory.

Handle num_bins outside of qneg

num_bins refers to the number of schemes calling qneg. It's currently set to 24, but should be either provided by CAMDEN or handled by the CCPP framework.

Efficiency improvements for CAM physics

This issue has been created to be a location where people can list possible efficiency modifications to various physics schemes that currently can't be applied due to the need to maintain bit-for-bit (b4b) reproducibility with the results from CAM.

Once all of the various schemes needed to reproduce CAM have been converted and verified, then these efficiency improvements can be applied.

To start, in apply_heating_rate_run in utilities/physics_tendency_updaters.F90, instead of doing:

 do klev = 1, nz
    temp(:, klev) = temp(:, klev) + (heating_rate(:, klev) * dt / cpair)
    dTdt_total(:, klev) = dTdt_total(:, klev) + (heating_rate(:, klev) / cpair)
 end do

One could do:

 cpair_inv = 1._kind_phys/cpair
 do klev = 1, nz
    temp(:, klev) = temp(:, klev) + (heating_rate(:, klev) * dt * cpair_inv)
    dTdt_total(:, klev) = dTdt_total(:, klev) + (heating_rate(:, klev) * cpair_inv)
 end do

which would reduce the number of (relatively more expensive) division calculations that are performed.

Feel free to add to this issue if any other efficiency improvements that could produce round-off changes are found.

Update Kessler for CAMDEN

Some standard names do not match the wiki names.
Some code has unused variables which cause compile warnings.

GW parameterization to CCPP

Required atmospheric physics updates

After going through the CAM names with scientists, the following standard names need to be updated:

1. reference_pressure_at_surface -> reference_pressure
2. rain_water_mixing_ratio_wrt_moist_air -> rain_mixing_ratio_wrt_moist_air
3. rain_water_mixing_ratio_wrt_dry_air -> rain_mixing_ratio_wrt_dry_air
4. ln_of_air_pressure_at_interface -> ln_air_pressure_at_interface
5. pressure_thickness -> air_pressure_thickness
6. pressure_thickness_of_dry_air -> air_pressure_thickness_of_dry_air
7. geopotential_at_surface -> surface_geopotential
8. reciprocal_of_pressure_thickness -> reciprocal_of_air_pressure_thickness
9. x_wind -> eastward_wind
10. y_wind -> northward_wind
11. geopotential_height -> geopotential_height_wrt_surface
12. tendency_of_x_wind -> tendency_of_eastward_wind
13. tendency_of_x_wind_due_to_model_physics -> tendency_of_eastward_wind_due_to_model_physics
14. tendency_of_y_wind -> tendency_of_northward_wind
15. tendency_of_y_wind_due_to_model_physics -> tendency_of_northward_wind_due_to_model_physics

Also a ChangeLog file needs to be added that records the modifications made for each new tag, starting with the one created to fix this issue.

Change directory name from zm to zhang_mcfarlane

What is the feature/what would you like to discuss?

@swrneale requested that the name of the directory should be zhang_mcfarlane instead of zm. This name will be more descriptive and allow folks to understand what is in this directory.

Is there anyone in particular you want to be part of this conversation?

No response

Will this change (regression test) answers?

No

Will you be implementing this enhancement yourself?

Yes

TUV-x in MUSICA wrapper

Add the creation of a TUV-x photolysis calculator to the MUSICA wrapper

Acceptance Criteria

• The MUSICA wrapper creates an instance of the TUV-x calculator during initialization based on a configuration file
• Photolysis rate constants are calculated at run time (initially for the Chapman mechanism, and with fixed conditions specified in the configuration file)
• An instance of the TUV-x calculator is created for each OpenMP thread

Ideas

• Follow the same logic used to create instances of the MICM solver

Missing kessler_update?

suite_kessler.xml still has a call to kessler_update but that file does not seem to have made it to the current master. Did it get lost in the directory rearrangement?

Implement Held-Suarez suite

Port the Held-Suarez suite to the CCPP.

Wrong intent in safe_set

The safe_set routine in state_converters.F90 has var as intent(out). However, this allows the value of var to be undefined as you enter the routine. When this happens (happens sometimes with nag compiler), the test for (var == unset) will fail. Also, the else clause fails to set the value which is an error.
I suggest that the intent be change to inout.

How should physics scheme tendencies be accumulated over the timestep?

As pointed out by @gold2718 in pull request #7 , it is currently unclear how changes in, say, tracer quantities should be gathered or accumulated from each physics scheme and then passed on to the dycore. There are currently three options on the table (although feel free to add more):

• Keep the current scheme (i.e., only track updated quantities)

• Move to accumulating tendencies (for passing back to the dycore)

• Have CAM accumulate the type of tracer feedback required by the dycore (e.g., updated quantity for FV, tendency for SE).

A decision needs to be made at some point, but for now this issue purely exists as reminder to discuss the different possibilities. Thanks!

Held-Suarez improvements

Make changes requested in #23.

Need to update geopotential_t to use "generalized" virtual temperature

Currently in CAM the calculation of geopotential height uses "generalized" virtual temperature, which accounts for all of the possible thermodynamically active constituents that the model simulates. However, in the CCPP-ized version of geopotential_t only water vapor is used, resulting in a mismatch between CAM and CAMDEN (or any other CCPP-enabled model which uses the CCPP-ized geopotential_t scheme).

To remedy this problem, the CCPP constituents array needs to be passed in along with information on which constituents are "thermodynamically active". This information should probably be contained within the ccpp_constituent_properties_array structure provided by capgen via NCAR/ccpp-framework#468.

Fix standard_names to the April 2021 version

After reviewing standard names and syncing them with outside collaborators, the variables in atmospheric_physics need updating to match the NCAR/CCPPStandardNames repo. This will match the version that exists in early April 2021.

"calc_exner_run" routine should be given reference pressure argument

The calc_exner_run subroutine in state_converters.F90 currently uses a hard-coded value for the Exner reference pressure. However, this can cause mis-matches with the host model if a different reference pressure is being used elsewhere. Thus to avoid this the reference pressure should be an argument that is passed in to cacl_exner_run, which ideally will come from the host model itself, or at least be consistent with the rest of the schemes in the physics suite.

held_suarez_1994 SDF needs the `geopotential_t` scheme.

Without it not only does it not match what is happening in CAM, but with the latest version of the CCPP-framework the SE dycore is no longer able to properly link with the geopotential_t_run subroutine needed to calculate derived quantities in the dynamics-physics coupling layer.

Add ccpp'ized ZM

Add CCPP layers to ZM schemes

Use https://github.com/climbfuji/ccpp-physics/tree/feature/iap_dom as a guide

See: https://docs.google.com/document/d/1jHLVbUCUhdEtY8puVV5FRnnj0yWdlrrw7j1jpNBnMa4/edit for info on why it can not be used as a dropin

The variable "ccpp_error_message" needs to have units of "none"

Currently all instances of ccpp_error_message in this repo have units of one (1). However, according to the official CCPP standard names dictionary ccpp_error_message should have units of none.

This matters because without the correct units the latest version of the CCPP-framework will error out.

Remove "use" statements from qneg

Pass in variables as inputs when possible; use dependencies.

Put back in total_tendency_of_air_temperature in kessler

total_tendency_of_air_temperature should not have been removed from Kessler and replaced with tendency_of_air_temperature.

Incorporate physics updaters into Kessler

Code will need to be moved out of kessler_update and into kessler.F90 to make appropriate variables available for use in apply_tendency_of_air_pressure_run. Also, a new scheme may need to be added to calculate dry static energy.

Register chemical species from MICM wrapper

Allow MICM to tell the host model what chemical species should be included in the state and provide their chemical/physical properties.

Acceptance Criteria

• The set of chemical species and their molecular weights from a MICM configuration are communicated to CAM-SIMA at run-time to set the model's constituents array.
• The correct species concentrations are updated during the "run" phase in the MICM wrapper.

Ideas

• Create a micm_register function that initially will be called directly by CAM-SIMA to set the constituents array. (Eventually, this register function may become a standard feature of the CCPP framework)
• The micm_register function should return an array of type ccpp_constituent_properties_t that will be used as CAM-SIMA sets its comprehensive set of constituents here

Correct algorithm bugs in the Kessler physics routine

The temporal subcycling algorithm in Kessler is broken.
The hardcoded value of kappa is incorrect and should be aligned with the standard CESM value.

Fix zvir standard name in geopotential_t.meta

zvir has this standard name in geopotential_t.meta:

composition_dependent_ratio_of_dry_air_to_water_vapor_gas_constants_minus_one

but it should be the other way:

composition_dependent_ratio_of_water_vapor_to_dry_air_gas_constants_minus_one

Need to remove CAM6 suite name conflict

A new namelist implementation in CAMDEN involves searching for names of suites as specified in the SDFs themselves, as opposed to just using the SDF file names. This means that two SDFs in this repo cannot have the exact same suite name as specified by the suite XML tag.

Currently this naming conflict only applies to suite_cam6.xml and suite_cam6_silhs.xml, which both have the cam6 suite name. Given that none of these SDFs are actually usable at the moment, the easiest solution would simply be to change the suite name in suite_cam6_silhs.xml from cam6 to cam6_silhs.

Update MICM interface to run simple MICM configuration

Update the MICM CCPP wrapper to use new MUSICA functions introduced with NCAR/musica#35

Have the wrapper create an instance for some very simple chemical system and solve at each timestep based on fixed conditions (no use of or updating of the CAM-SIMA state)

Kessler physics needs to compute relative humidity

Kessler needs to produce the relative humidity instead of having it computed in cam_diagnostics. This guarantees that the maximum relative humidity is 100%.

Create generalized mixing ratio conversion schemes

Now that the CCPP-framework's constituent object is up and running, it would be great to figure out a way to replace the species-specific wet-to-dry and dry-to-wet physics schemes with more generic routines that can convert all wet constituent variables to dry and visa versa.

Need to implement qneg_surface (qneg4)

Need to add unit tests for utility schemes

Given the implementation of a unit testing framework for the atmospheric_physics repo in PR #78, there is now an opportunity to create some unit tests for the various physics schemes inside the utilities directory.

This would be particularly beneficial because the tests done in CAM-SIMA are usually for an entire physics suite, where the utility schemes are grouped together, as opposed to each individual utility scheme as proposed here. Plus it would allow for additional test coverage for a PR without necessarily requiring the user to run CAM-SIMA.

Rayleigh Friction to CCPP

Okay, we will see how this goes with 8 lines of operative code.....

Kessler suite uses two versions of rair

Kessler physics requires the gas constant for dry air in order to compute the inverse of kappa. However, the geopotential_t function uses the height-dependent version of this quantity.

While this is unlikely to cause any problem for reasonable Kessler physics simulations (Kessler physics does not make much sense above altitudes where rair is likely to vary), is this a suite usage that should be cleaned up?

At least CAMDEN / CCPP Framework generated the correct code for this situation!

Need xmllint Github Action

Given that there will soon be multiple XML files (of at least two different types) in this repo that host models will depend on, it could help to implement an automatic xmllint Github Action that ensures that any new XML file validates correctly.

This could likely just be a copy of the code eventually used for the same action described in ESCOMP/CAM-SIMA#188, except with the registry schema replaced with the CCPP SDF schema.