Adds additional lapse rate options for moist_lapse

[omiyawaki]

Description Of Changes

This request adds lapse rate options for the moist_lapse function in MetPy. Currently moist_lapse calculates a moist adiabat by integrating the moist adiabatic lapse rate defined in the AMS glossary entry on adiabatic lapse rates. However, alternative definitions of the moist adiabatic lapse rate exist such as the pseudoadiabatic and reversible moist adiabatic lapse rate. Additionally, there are simple expressions for lapse rates that include the effect of convective entrainment (e.g., Singh and O'Gorman 2013, Romps 2014). This pull request adds these alternative lapse rates to the moist_lapse and parcel_profile functions.

The modifications are simple. I added 2 optional arguments to moist_lapse and parcel_profile: lapse_type and params. lapse_type is a string that specifies the lapse rate type and params is a dictionary that includes additional input parameters that are needed for the entraining lapse rates. I added alternative lapse rate definitions as dt_"lapse_type" and an if statement defines dt based on the chosen lapse_type. lapse_type defaults to the existing lapse rate definition so this change retains the previous behavior of moist_lapse and parcel_profile (i.e., they work just as before when lapse_type and params are not specified in the function call).

This pull request closes #434 and may also be useful for #3187.
 

Checklist

• Closes Add reversible saturated adiabatic paths #434
• Tests added (see below for a simple example of the new functionality)
• Fully documented (updated commented documentation in source code but not yet in the html doc)

Example

import sys
metpy_path='/project/amp/miyawaki/software/MetPy' # path to modified metpy library
sys.path.insert(1,'%s/src'%(metpy_path))
import numpy as np
from metpy.units import units
from metpy.calc import moist_lapse,dry_lapse

tl=300*units.K  # initial parcel temperature
pa=(1e2*np.array([1000,925,850,700,600,500,400,300]))*units.Pa

# Parameters for SO13 lapse rate
h0=8e3 # scale height [m]
p0=1.013e5 # reference surface pressure [Pa]
ep0=0.75 # entrainment parameter [dimensionless]
rh0=0.8 # environment relative humidity [dimensionless]

# Parameters for R14 lapse rate
ep=0.5e-3 # entrainment rate [m**-1]
de=ep # detrainment rate [m**-1]

# Compute temperature profiles
print(moist_lapse(pa,tl)) # existing functionality of moist_lapse
print(moist_lapse(pa,tl,lapse_type='pseudoadiabatic')) # pseudoadiabat
print(moist_lapse(pa,tl,lapse_type='reversible')) # reversible moist adiabat
print(moist_lapse(pa,tl,lapse_type='so13',params={'h0':h0,'p0':p0,'ep0':ep0,'rh0':rh0})) # Singh and O'Gorman entraining plume
print(moist_lapse(pa,tl,lapse_type='r14',params={'de':de,'ep':ep})) # Romps entraining plume

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.

---

Osamu Miyawaki seems not to be a GitHub user. You need a GitHub account to be able to sign the CLA. If you have already a GitHub account, please add the email address used for this commit to your account.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

[wx4stg]

This has been a long wanted feature, and makes some progress towards achieving #461 (which I said I would work on as I need it for a personal project, and then... school happened... oof)

Anyway, I'm not very available to help with this but consider me cheering from the sidelines for this PR!

[dcamron]

Thank you so much for your work on this! As shouted out above, there absolutely is a need for this, and we will gladly take your help and contributions to get us there.

Before you spend a ton of additional time and work on this, we do have some considerations that have come up recently that might put this on pause:

• MetPy currently has funding dedicated to support enhancing its performance and scalability. moist_lapse is one of the key bottlenecks identified for refactoring and improvement, and so the body of that code is likely to change heavily in the near future. That will end up affecting how your work here could best be implemented.
• We have a variety of long-standing requests (eg Alternative calculations #142 xarray parcel functions #1968, above tags, and more) for support of alternative calculation schemes, constant sets, parcel paths etc. and we've yet to settle on the best interfaces for these, separate and as a whole.

We think your input could be incredibly valuable to both of these pieces moving forward, so please do stick around and consider dropping by one of our many community developer calls (#3166) in the near future. If the regularly scheduled call doesn't work for you, many of us can make ourselves available to meet to chat with you about this work and carrying it forward into performance and flexibility work described above!

[omiyawaki]

Thank you for filling me in on these developments, @dcamron. I'm happy to participate in future discussions on moist_lapse.

Will part of refactoring and improving moist_lapse involve breaking changes to existing scripts that call moist_lapse? If so, I think it makes sense to put my pull request on pause because the current usage of moist_lapse will become obsolete.

If not, is there a possibility for these changes to be incorporated on a faster timeline than what is planned for the overhaul of moist_lapse? The reason I ask is because we are hoping to make these new functionalities available to a broad audience as part of a review paper we are writing on tropical lapse rates. I think having these features included in the main branch (vs asking people to download my fork) will lead to a greater adoption of these tools. The paper is currently on schedule to be submitted by the end of the year.

[dcamron]

I chat with @dopplershift and we're totally on board with prioritizing getting this in for the broader community alongside this review paper. Our performance refactoring will mostly happen "under the hood", and we should be able to do the work to fit your formulations into it. We will need to settle for sure on the expanded moist_lapse interface, but your work so far is great and we absolutely want to get it in. We haven't settled on what this interface could be just yet, but we have some ideas. Would you be able to join one of our Dev Calls? (#3166, next meeting is this Thursday, 16 Nov 2023 at 9 am MST / 1600 UTC) If not, we'd love to schedule a meeting to chat and get this included soon!

Thanks for your work and communication.

[omiyawaki]

Sounds great! I can join the meeting this Thursday from 9-9:30 am MST (I have another meeting at 9:30).

[deeplycloudy]

As a possible unit test case, see Table 4.2 in Emanuel, p. 133. In reproducing that table in the past there were some subtleties. The text doesn't say, but it uses variable latent heat of varporization (K
irchoff's law), but a constant specific heat of liquid water $c_l$ of about 4190 J/kg K. Technically, $c_l$ has a pretty large departure at very cold T (Pruppacher and Klett has a formula for this).

Attached is the notebook that I used to do the reproduction in the past. It has some commentary at the bottom that might be helpful.