Merge pull request #3690 from dopplershift/qvector-units

Fix q_vector units w/ default static stability

Author: dcamron

Diff for: examples/calculations/QVector.py

@@ -23,8 +23,10 @@
 # Calculate the temperature advection of the flow
 tadv = mpcalc.advection(ds.temperature, ds.uwind, ds.vwind)
 
-# Calculate the q-vectors
-u_qvect, v_qvect = mpcalc.q_vector(ds.uwind, ds.vwind, ds.temperature, 850 * units.hPa)
+# Calculate the q-vectors. Passing in a fixed value of static stability, but could also
+# use `mpcalc.static_stability()`.
+u_qvect, v_qvect = mpcalc.q_vector(ds.uwind, ds.vwind, ds.temperature, 850 * units.hPa,
+                                   static_stability=0.02 * units('J / kg / Pa^2'))
 
 # start figure and set axis
 fig, ax = plt.subplots(figsize=(5, 5))

Diff for: src/metpy/calc/kinematics.py

@@ -1275,7 +1275,8 @@ def inertial_advective_wind(
     broadcast=('u', 'v', 'temperature', 'pressure', 'static_stability', 'parallel_scale',
                'meridional_scale')
 )
-@check_units('[speed]', '[speed]', '[temperature]', '[pressure]', '[length]', '[length]')
+@check_units('[speed]', '[speed]', '[temperature]', '[pressure]', '[length]', '[length]',
+             '[energy] / [mass] / [pressure]**2')
 def q_vector(
     u,
     v,
@@ -1307,6 +1308,12 @@ def q_vector(
               - 2 \nabla_p \cdot \vec{Q} -
                   \frac{R}{\sigma p} \beta \frac{\partial T}{\partial x}
 
+    By default, this function uses a unitless value of 1 for ``static_stability``, which
+    replicates the functionality of the GEMPAK ``QVEC`` function. If a value is given for
+    ``static_stability``, it should have dimensionality of ``energy / mass / pressure^2``, and
+    will result in behavior that matches that of GEMPAK's ``QVCL`` function;
+    `static_stability` can be used to calculate this value if desired.
+
     Parameters
     ----------
     u : (..., M, N) `xarray.DataArray` or `pint.Quantity`