Derived Variables ================= Met.3D can compute a range of derived atmospheric quantities on-the-fly from gridded input data. Defining input variable mapping --------------------------------- When loading a dataset, you need to map the variable names in your data files to the CF standard names that Met.3D uses internally. In the "Add dataset" dialog, click the "Variable mapping" button to open a table editor where you can define these mappings interactively. Alternatively, specify the mapping as a ``/``-separated string of ``CF standard name:input variable name`` pairs. For example, for ECMWF GRIB data: .. code-block:: eastward_wind:u/northward_wind:v/air_temperature:t/specific_humidity:q/surface_geopotential:z/surface_air_pressure:sp/surface_temperature:2t/lwe_thickness_of_precipitation_amount:tp/geopotential:z For NetCDF files, use the NetCDF variable names directly. For instance, if the u-wind variable is called ``u_wind``, the entry would be ``eastward_wind:u_wind``. .. _list of available derived variables: Available derived variables ----------------------------- As of Met.3D v2.0, the following derived variables are implemented. All variable names follow the `CF standard names`_ convention. Unless noted, variables support all grid and vertical level types. Wind ~~~~ * ``wind_speed`` * Horizontal wind speed. * Requires: eastward_wind, northward_wind. * Input level types: all. * Output: same level type as input. * ``magnitude_of_air_velocity`` * 3-D wind speed magnitude. * Requires: eastward_wind, northward_wind, upward_air_velocity. * Input level types: all. * Output: same level type as input. Temperature and thermodynamics ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ * ``air_potential_temperature`` * Potential temperature. * Requires: air_temperature. * Input level types: all. * Output: same level type as input. * ``equivalent_potential_temperature`` * Equivalent potential temperature; Bolton (MWR, 1980), Eq. 43. * Requires: air_temperature, specific_humidity. * Input level types: all. * Output: same level type as input. * ``ertel_potential_vorticity`` * Ertel potential vorticity; `LAGRANTO`_ formulation. A more generic implementation for other level types is available via ``potential_vorticity_baroclinic_metpy`` (see below). * Requires: eastward_wind, northward_wind, air_temperature, surface_air_pressure. * Input level types: HYBRID_SIGMA_PRESSURE_3D only. * Output: HYBRID_SIGMA_PRESSURE_3D. * ``potential_vorticity_baroclinic_metpy`` * Baroclinic potential vorticity (MetPy). More generic than ``ertel_potential_vorticity``; works on all level types. *Computed via the* :ref:`Python/MetPy interface `. * Requires: air_potential_temperature, air_pressure, eastward_wind, northward_wind. * Input level types: all. * Output: same level type as input. * ``static_stability_metpy`` * Static stability (MetPy). *Computed via the* :ref:`Python/MetPy interface `. * Requires: air_pressure, air_temperature. * Input level types: all. * Output: same level type as input. Geopotential and pressure ~~~~~~~~~~~~~~~~~~~~~~~~~ * ``surface_geopotential`` * Surface geopotential derived from geometric height; MetPy / Wallace & Hobbs (2006). * Requires: height_above_mean_sea_level (surface field, in metres). * Input level types: SINGLE_LEVEL. * Output: SINGLE_LEVEL. * ``geopotential_height`` * Geopotential height. * Requires: air_temperature, specific_humidity, surface_geopotential, surface_air_pressure, surface_temperature. * Input level types: all (3D inputs at any level type; surface inputs at SINGLE_LEVEL). * Output: same level type as the 3D inputs. * ``geopotential_height_from_geopotential`` * Geopotential height from geopotential field (divides by 9.81 m² s⁻²). * Requires: geopotential. * Input level types: all. * Output: same level type as input. * ``air_pressure`` * 3-D air pressure field reconstructed from grid level specification; no input data needed. * Requires: nothing. * Input level types: PRESSURE_LEVELS_3D, AUXILIARY_PRESSURE_3D, HYBRID_SIGMA_PRESSURE_3D. * Output: same level type as input. * ``omega_hydrostatic_approximation`` * Vertical velocity in pressure coordinates (ω, Pa s⁻¹); MetPy / Wallace & Hobbs (2006). * Requires: upward_air_velocity, air_temperature. * Input level types: all. * Output: same level type as input. Moisture and precipitation ~~~~~~~~~~~~~~~~~~~~~~~~~~ * ``relative_humidity`` * Relative humidity; saturation vapour pressure after Huang (JAMC, 2018). * Requires: air_temperature, specific_humidity. * Input level types: all. * Output: same level type as input. * ``dew_point_temperature`` * Dew-point temperature. * Requires: specific_humidity. * Input level types: all. * Output: same level type as input. * ``lwe_thickness_of_precipitation_amount_Nh`` * N-hourly total precipitation (N = 1, 3, 6, 12, 24), computed as the difference of accumulated totals over N hours. * Requires: lwe_thickness_of_precipitation_amount at the current and N-hours-prior time steps. * Input level types: all (in practice SINGLE_LEVEL for precipitation data). * Output: same level type as input. * ``precipitation_amount_Nh`` * Same as above but without the ``lwe_thickness_of_`` prefix (N = 1, 3, 6, 12, 24), for data files that omit it. * Requires: precipitation_amount at the current and N-hours-prior time steps. * Input level types: all (in practice SINGLE_LEVEL). * Output: same level type as input. * ``magnitude_of_vertically_integrated_horizontal_transport_of_moisture__from_LEVELTYPE`` * Vertically integrated horizontal moisture flux magnitude. Registered separately for each 3D level type; ``LEVELTYPE`` in the name is replaced accordingly. * Requires: surface_air_pressure, eastward_wind, northward_wind, specific_humidity. * Input level types: HYBRID_SIGMA_PRESSURE_3D, PRESSURE_LEVELS_3D, AUXILIARY_PRESSURE_3D (one registration per type). * Output: SINGLE_LEVEL (vertically integrated → 2D field). * ``magnitude_of_horizontal_transport_of_moisture`` * Column-wise (not vertically integrated) horizontal moisture flux magnitude. * Requires: eastward_wind, northward_wind, specific_humidity. * Input level types: all. * Output: same level type as input. * ``lwe_thickness_of_atmosphere_water_vapor_content`` * Vertically integrated water vapour (IWV, kg m⁻²). * Requires: specific_humidity (any level type). * Input level types: all. * Output: SINGLE_LEVEL. * ``wet_bulb_temperature_metpy`` * Wet-bulb temperature (MetPy, Normand method — can be slow on large grids). *Computed via the* :ref:`Python/MetPy interface `. * Requires: air_pressure, air_temperature, dew_point_temperature. * Input level types: all. * Output: same level type as input. * ``wet_bulb_potential_temperature_metpy`` * Wet-bulb potential temperature (MetPy). *Computed via the* :ref:`Python/MetPy interface `. * Requires: air_pressure, air_temperature, dew_point_temperature. * Input level types: all. * Output: same level type as input. * ``hourly_mean_of_surface_downward_latent_heat_flux`` * Hourly mean surface downward latent heat flux (ERA5-specific; derived from accumulated flux). * Requires: integral_wrt_time_of_surface_downward_latent_heat_flux. * Input level types: all (in practice SINGLE_LEVEL for ERA5 surface flux data). * Output: same level type as input. Boundary layer ~~~~~~~~~~~~~~ * ``bulk_richardson_number`` * Bulk Richardson number. * Requires: geopotential_height, eastward_wind, northward_wind, air_temperature, specific_humidity, air_pressure. * Input level types: all. * Output: same level type as input. * ``blh_from_richardson_number`` * Boundary layer height derived from the bulk Richardson number (metres). * Requires: bulk_richardson_number, geopotential_height (any level type). * Input level types: all. * Output: SINGLE_LEVEL. Wind speed derivatives ~~~~~~~~~~~~~~~~~~~~~~ Used by the :doc:`Jetcore detection actor<../actors/jetcore_detection>`. All derivatives below require at least eastward_wind and northward_wind. Derivatives in z additionally require geopotential_height. All support all input level types and output the same level type as input. * ``dVs_dn`` — ∂Vs/∂n: first derivative perpendicular to wind direction. * ``dVs_dz`` — ∂Vs/∂z: first derivative, vertical (upward). * ``dVs_dp`` — ∂Vs/∂p: first derivative along pressure. * ``d2Vs_dn2`` — ∂²Vs/∂n²: second derivative perpendicular to wind. * ``d2Vs_dz2`` — ∂²Vs/∂z²: second derivative, vertical. * ``d2Vs_dp2`` — ∂²Vs/∂p²: second derivative along pressure. * ``d2Vs_dndz`` — ∂²Vs/∂n∂z: mixed derivative (perpendicular × vertical). * ``d2Vs_dndp`` — ∂²Vs/∂n∂p: mixed derivative (perpendicular × pressure). Height-to-pressure conversion ------------------------------ For each surface 2-D field with height values in metres available in the loaded dataset, Met.3D automatically registers two derived variables: * ``air_pressure_at__from_standard_atmosphere`` — converts the height field to pressure using the `ICAO standard atmosphere`_. * ``air_pressure_at__from_geopotential_height`` — uses geopotential height for a more accurate conversion. For example, if a field ``BLH`` (boundary layer height in metres) is loaded, Met.3D automatically provides ``air_pressure_at_BLH_from_standard_atmosphere``. .. _python_derived_variables: Python/MetPy interface ---------------------- Several derived variables (marked *"Computed via the Python/MetPy interface"* in the list above) are computed through Met.3D's embedded Python interface using `MetPy `_ via an in-memory NetCDF buffer. Input data for the computation is passed as an ``xarray.Dataset`` to the corresponding Python function. See :doc:`python_interface` for the full Python interface documentation. If you have already implemented a computation in Python, or want to use additional MetPy functions, adding new Python-derived variables is straightforward. See :ref:`adding_derived_variables` in the developer manual. Source code ----------- Derived variable computation is in ``src/data/derivedvars/``: * ``_ The base class is ``MDerivedDataFieldProcessor`` (``deriveddatafieldprocessor.h``). Standard variables are implemented in ``derivedmetvars_standard.cpp``. All processors are registered in ``MDerivedMetVarsDataSource`` (``derivedmetvarsdatasource.cpp``). For developer guidance on adding new derived variables, see :ref:`adding_derived_variables` in the developer manual. .. _`CF standard names`: http://cfconventions.org/standard-names.html .. _`LAGRANTO`: https://iacweb.ethz.ch/staff/sprenger/lagranto/ .. _`ICAO standard atmosphere`: https://en.wikipedia.org/wiki/International_Standard_Atmosphere