Mixed-layer CAPE/CIN accepts depth in units of height

[23ccozad]

Previously, mixed_layer_cape_cin() only supported layer depth as a pressure. To be consistent with mixed_parcel(), which takes depth as a height or pressure, this PR adds the ability to provide layer depth as a height.

If the depth is in units of height, it would be nice to have a height profile passed in as well. However, in the case that a height profile is not passed, a warning is issued to let the user know that their height was converted to pressure with height_to_pressure_std().

Full disclosure: I haven't taken any thermo classes, so this PR is the product of many Google searches and probably has some errors that I didn't catch. Please don't hesitate to point those out, and provide any other comments as well.

Checklist

• Closes Support depth in meters for mixed_layer_cape_cin #1718
• Tests added
• Fully documented

[23ccozad]

While we're taking a look at mixed_layer_cape_cin(), I wanted to bring up something that could be a bit confusing. Our documentation for mixed_layer_cape_cin() says:

Kwargs for mixed_parcel can be provided, such as depth.

The possible kwargs for mixed_parcel() are parcel_start_pressure, height, bottom, depth, and interpolate. In my opinion, the usage of all of these kwargs make sense when used in the context of mixed_layer_cape_cin(), except for bottom. bottom specifies the lower bound of the mixed layer.

In mixed_layer_cape_cin(), we replace all data between (lowest data point) and (lowest data point + depth) with the result from mixed_parcel(). However, if bottom is specified to be something other than the surface (and I believe we're treating the lowest data point in the sounding to be the surface), then that's being passed on to mixed_parcel(), but not being accounted for in mixed_layer_cape_cin() when we replace the mixed layer with the mixed parcel.

If this analysis is correct, I see two possible options:

1. Change mixed_layer_cape_cin() to allow the mixed layer to not be at the surface. Although, I've never seen MLCAPE or MLCIN have a mixed layer above the surface. Maybe someone with more experience could chime in on this.
2. Somehow prevent users from being able to pass bottom in mixed_layer_cape_cin(), forcing bottom to always be at the surface.

[dopplershift]

I'm currently trying to figure out how parcel_start_pressure is different than bottom in the call to mixed_parcel.

I wasn't aware of Quantity.check()--nice find! Would be good to replace all the places where we're manually checking .dimensionality == with that.

[23ccozad]

It looks like parcel_start_pressure ends up being returned as the pressure of the mixed parcel, but it also affects the temperature and dewpoint of the parcel as well. I haven't dug into the details with these lines:

mean_temperature = mean_theta * exner_function(parcel_start_pressure)

mean_vapor_pressure = vapor_pressure(parcel_start_pressure, mean_mixing_ratio)
mean_dewpoint = globals()['dewpoint'](mean_vapor_pressure)

On the other hand, bottom gets passed to mixed_layer(), which provides mean_theta and mean_mixing_ratio used in the lines above.

The more I look into this, the less clear it is. Will try to spend some more time on this.

[dopplershift]

So exner is more or less calculating temperature from potential temperature. To the weird thing here is it's calculating a mixed parcel from bottom to top, and then bringing it down dry adiabatically to the start pressure.

[kgoebber]

From the name of the height kwarg it is not clear that this represents an array of height values associated with a vertical profile. Would a variable name of height_profile be more appropriate and descriptive for our users? I think this would also help alleviate some confusion between that kwarg and depth as they are clearly distinct.