From 407eb0d5aa561f52adb396e3319d1feb7339d9c7 Mon Sep 17 00:00:00 2001 From: Ryan May Date: Wed, 13 Nov 2024 16:12:04 -0700 Subject: [PATCH 1/2] DOC: Improve q_vector documentation (Fixes #3689) Clarify the optional role of static_stability and how that maps to various GEMPAK calculations. Also ensure that values for `static_stability` are properly checked for dimensionality. --- src/metpy/calc/kinematics.py | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/src/metpy/calc/kinematics.py b/src/metpy/calc/kinematics.py index dc2d8275bb..f79d7971d0 100644 --- a/src/metpy/calc/kinematics.py +++ b/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` From 5bebff4ff198763569ab968b0ca02f924cd11546 Mon Sep 17 00:00:00 2001 From: Ryan May Date: Thu, 2 Jan 2025 16:47:38 -0700 Subject: [PATCH 2/2] DOC: Pass static_stability in QVector example Helps make clear that this is an option for this calculation. Addresses part of #3689. --- examples/calculations/QVector.py | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/examples/calculations/QVector.py b/examples/calculations/QVector.py index b019afdf4e..d9eebdbd65 100644 --- a/examples/calculations/QVector.py +++ b/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))