improver.psychrometric_calculations.psychrometric_calculations module

Module to contain Psychrometric Calculations.

class improver.psychrometric_calculations.psychrometric_calculations.FallingSnowLevel(precision=0.005, falling_level_threshold=90.0, grid_point_radius=2)

Bases: object

Calculate a field of continuous falling snow level.

__init__(precision=0.005, falling_level_threshold=90.0, grid_point_radius=2)

Initialise class.

Keyword Arguments:  

• precision (float) – The precision to which the Newton iterator must converge before returning wet bulb temperatures.
• falling_level_threshold (float) – The cutoff threshold for the Wet-bulb integral used to calculate the falling snow level.We are integrating to the threshold that is presumed to indicate the level at which snow has melted back to rain. Above this level we should have falling snow.
• grid_point_radius (int) – The radius in grid points used to calculate the maximum height of the orography in a neighbourhood as part of this calculation.

static fill_in_by_horizontal_interpolation(snow_level_data, max_in_nbhood_orog, orog_data)

Fill in any remaining unset areas in the snow falling level by using linear horizontal interpolation across the grid. As snow falling levels at the highest height levels will be filled in by this point any points that still don’t have a valid snow falling level have the snow falling level at or below the surface orography. This function uses the following steps to help ensure that the filled in values are above or below the orography:

1. Fill in the snow-level for points with no value yet set using horizontal interpolation from surrounding set points. Only interpolate from surrounding set points at which the snow falling level is below the maximum orography height in the region around the unset point. This helps us avoid spreading very high snow falling levels across areas where we had missing data.
2. Fill any gaps that still remain where the linear interpolation has not been able to find a value because there is not enough data (e.g at the corners of the domain). Use nearest neighbour interpolation.
3. Check whether despite our efforts we have still filled in some of the missing points with snow falling levels above the orography. In these cases set the missing points to the height of orography.

We then return the filled in array, which hopefully has no more missing data.

Parameters:

• snow_level_data (numpy.array) – The snow falling level array, filled with values for points whose wet bulb temperature integral crossed the theshold.
• max_in_nbhood_orog (numpy.array) – The array containing maximum of the orography field in a given radius.
• orog_data (numpy.data) – The array containing the orography data.

Returns:

The snow falling level array with missing data filled by horizontal interpolation.

Return type:

snow_filled (numpy.array)

fill_in_high_snow_falling_levels(snow_level_data, orog_data, highest_wb_int_data, highest_height)

Fill in any data in the snow falling level where the whole wet bulb temperature integral is above the the threshold. Set these points to the heighest height level + orography.

Parameters:

• snow_level_data (np.array) – Falling snow level data (m).
• orog_data (np.array) – Orographic data (m)
• highest_wb_int_data (np.array) – Wet bulb integral data on highest level (K m).
• highest_height (float) – Highest height at which the integral starts (m).

fill_in_sea_points(snow_level_data, land_sea_data, max_wb_integral, wet_bulb_temperature, heights)

Fill in any sea points where we have not found a snow falling level by the time we get to sea level, i.e. where the whole wet bulb temperature integral is below the threshold.

This function finds a linear fit to the wet bulb temperature close to sea level and uses this to find where an extrapolated wet bulb temperature integral would cross the threshold. This results in snow falling levels below sea level for points where we have applied the extrapolation.

Assumes that height is the first axis in the wet_bulb_integral array.

Parameters:

• snow_level_data (numpy.array) – The snow falling level array, filled with values for points whose wet bulb temperature integral crossed the theshold.
• land_sea_data (numpy.array) – The binary land-sea mask
• max_wb_integral (numpy.array) – The wet bulb temperature integral at the final height level used in the integration. This has the maximum values for the wet bulb temperature integral at any level.
• wet_bulb_temperature (numpy.array) – The wet bulb temperature profile at each grid point, with height as the leading dimension.
• heights (numpy.array) – The vertical height levels above orography, matching the leading dimension of the wet_bulb_temperature.

find_extrapolated_falling_level(max_wb_integral, gradient, intercept, snow_falling_level, sea_points)

Find the snow falling level below sea level using the linear extrapolation of the wet bulb temperature integral and update the snow falling level array with these values.

The snow falling level is calculated from finding the point where the integral of wet bulb temperature crosses the falling level threshold.

In cases where the wet bulb temperature integral has not reached the threshold by the time we reach sea level, we can find a fit to the wet bulb temperature profile near the surface, and use this to estimate where the snow falling level would be below sea level.

The difference between the wet bulb temperature integral at the threshold and the wet bulb integral at the surface is equal to the integral of the wet bulb temperature between sea level and the negative height corresponding to the snow falling level. As we are using a simple linear fit, we can integrate this to find an expression for the extrapolated snow falling level.

The form of this expression depends on whether the linear fit of wet bulb temperature crosses the height axis above or below zero altitude.

If we have our linear fit of the form:

\[{{wet\:bulb\:temperature} = m \times height + c}\]

and let \(I\) be the wet bulb temperature integral we have found above sea level.

If it crosses above zero, then the limits on the integral are the snow falling level and zero and we find the following expression for the snow falling level:

\[{{snow\:falling\:level} = \frac{c \pm \sqrt{ c^2-2 m (threshold-I)}}{-m}}\]

If the linear fit crosses below zero the limits on our integral are the snow falling level and the point where the linear fit crosses the height axis, as only positive wet bulb temperatures count towards the integral. In this case our expression for the snow falling level is:

\[{{snow\:falling\:level} = \frac{c \pm \sqrt{ 2 m (I-threshold)}}{-m}}\]

Parameters:

• max_wb_integral (numpy.array) – The wet bulb temperature integral at sea level.
• gradient (numpy.array) – The gradient of the line of best fit we are using in the extrapolation.
• intercept (numpy.array) – The intercept of the line of best fit we are using in the extrapolation.
• snow_falling_level (numpy.array) – The snow falling level array with values filled in with snow falling levels calculated through extrapolation.
• points (sea) – A boolean array with True where the points are sea points.

find_falling_level(wb_int_data, orog_data, height_points)

Find the falling snow level by finding the level of the wet-bulb integral data at the required threshold. Wet-bulb integral data is only available above ground level and there may be an insufficient number of levels in the input data, in which case the required threshold may lie outside the Wet-bulb integral data and the value at that point will be set to np.nan.

Parameters:

• wb_int_data (np.array) – Wet bulb integral data on heights
• orog_data (np.array) – Orographic data
• heights (np.array) – heights agl

Returns:

Falling snow level data asl.

Return type:

snow_level_data (np.array)

find_max_in_nbhood_orography(orography_cube)

Find the maximum value of the orography in the region around each grid point in your orography field by finding the maximum in a neighbourhood around that point.

Parameters:orography_cube (iris.cube.Cube) – The cube containing a single 2 dimensional array of orography data Returns:The cube containing the maximum in a neighbourhood of the orography data. Return type:max_in_nbhood_orog (iris.cube.Cube)

static linear_wet_bulb_fit(wet_bulb_temperature, heights, sea_points, start_point=0, end_point=5)

Calculates a linear fit to the wet bulb temperature profile close to the surface to use when we extrapolate the wet bulb temperature below sea level for sea points.

We only use a set number of points close to the surface for this fit, specified by a start_point and end_point.

Parameters:

• wet_bulb_temperature (numpy.array) – The wet bulb temperature profile at each grid point, with height as the leading dimension.
• heights (numpy.array) – The vertical height levels above orography, matching the leading dimension of the wet_bulb_temperature.
• sea_points (numpy.array) – A boolean array with True where the points are sea points.

Keyword Arguments:  

• start_point (int) – The index of the the starting height we want to use in our linar fit.
• end_point (int) – The index of the the end height we want to use in our linear fit.

Returns:

tuple containing

gradient (numpy.array) - An array, the same shape as a 2D slice of the wet_bulb_temperature input, containing the gradients of the fitted straight line at each point where it could be found, filled with zeros elsewhere.

intercept (numpy.array) - An array, the same shape as a 2D slice of the wet_bulb_temperature input, containing the intercepts of the fitted straight line at each point where it could be found, filled with zeros elsewhere.

Return type:

(tuple)

process(temperature, relative_humidity, pressure, orog, land_sea_mask)

Calculate the wet bulb temperature integral by firstly calculating the wet bulb temperature from the inputs provided, and then calculating the vertical integral of the wet bulb temperature. Find the falling_snow_level by finding the height above sea level corresponding to the falling_level_threshold in the integral data. Fill in missing data appropriately.

Parameters:

• temperature (iris.cube.Cube) – Cube of air temperatures (K).
• relative_humidity (iris.cube.Cube) – Cube of relative humidities (%, converted to fractional).
• pressure (iris.cube.Cube) – Cube of air pressures (Pa).
• orog (iris.cube.Cube) – Cube of orography (m).
• land_sea_mask (iris.cube.Cube) – Cube containing a binary land-sea mask.

Returns:

Cube of Falling Snow Level above sea level (asl).

Return type:

falling_snow_level (iris.cube.Cube)

class improver.psychrometric_calculations.psychrometric_calculations.Utilities

Bases: object

Utilities for psychrometric calculations.

__init__()

Initialise class.

static calculate_d_enthalpy_dt(mixing_ratio, specific_heat, latent_heat, temperature_input)

Calculate the enthalpy gradient with respect to temperature.

Method from referenced UM documentation.

References

Met Office UM Documentation Paper 080, UM Version 10.8, last updated 2014-12-05.

Parameters:

• mixing_ratio (iris.cube.Cube) – Cube of mixing ratios.
• specific_heat (iris.cube.Cube) – Cube of specific heat capacities of moist air (J kg-1 K-1).
• latent_heat (iris.cube.Cube) – Cube of latent heats of condensation of water vapour (J kg-1).
• temperature_input (iris.cube.Cube) – A cube of temperatures (K, or converted).

Returns:

A cube of the enthalpy gradient with respect to temperature.

Return type:

iris.cube.Cube

static calculate_enthalpy(mixing_ratio, specific_heat, latent_heat, temperature)

Calculate the enthalpy (total energy per unit mass) of air (J kg-1).

Method from referenced UM documentation.

References

Met Office UM Documentation Paper 080, UM Version 10.8, last updated 2014-12-05.

Parameters:

• mixing_ratio (iris.cube.Cube) – Cube of mixing ratios.
• specific_heat (iris.cube.Cube) – Cube of specific heat capacities of moist air (J kg-1 K-1).
• latent_heat (iris.cube.Cube) – Cube of latent heats of condensation of water vapour (J kg-1).
• temperature (iris.cube.Cube) – A cube of air temperatures (K).

Returns:

A cube of enthalpy values calculated at the same points as the input cubes (J kg-1).

Return type:

enthalpy (iris.cube.Cube)

static latent_heat_of_condensation(temperature_input)

Calculate a temperature adjusted latent heat of condensation for water vapour using the relationship employed by the UM.

Parameters:temperature_input (iris.cube.Cube) – A cube of air temperatures (Celsius, converted if not). Returns:Temperature adjusted latent heat of condesation (J kg-1). Return type:iris.cube.Cube

static saturation_vapour_pressure_goff_gratch(temperature)

Saturation Vapour pressure in a water vapour system calculated using the Goff-Gratch Equation (WMO standard method).

Parameters:temperature (iris.cube.Cube) – Cube of temperature which will be converted to Kelvin prior to calculation. Valid from 173K to 373K Returns:Cube containing the saturation vapour pressure of a pure water vapour system. A correction must be applied to the data when used to convert this to the SVP in air; see the WetBulbTemperature.pressure_correct_svp function. Return type:svp (iris.cube.Cube)

References

Numerical data and functional relationships in science and technology. New series. Group V. Volume 4. Meteorology. Subvolume b. Physical and chemical properties of the air, P35.

static specific_heat_of_moist_air(mixing_ratio)

Calculate the specific heat capacity for moist air by combining that of dry air and water vapour in proportion given by the specific humidity.

Parameters:mixing_ratio (iris.cube.Cube) – Cube of specific humidity (fractional). Returns:Specific heat capacity of moist air (J kg-1 K-1). Return type:iris.cube.Cube

class improver.psychrometric_calculations.psychrometric_calculations.WetBulbTemperature(precision=0.005)

Bases: object

A plugin to calculate wet bulb temperatures from air temperature, relative humidity, and pressure data. Calculations are performed using a Newton iterator, with saturated vapour pressures drawn from a lookup table using linear interpolation.

The svp_table used in this plugin is imported (see top of file). It is a table of saturated vapour pressures calculated for a range of temperatures. The import also brings in attributes that describe the range of temperatures covered by the table and the increments in the table.

__init__(precision=0.005)

Initialise class.

Parameters:precision (float) – The precision to which the Newton iterator must converge before returning wet bulb temperatures.

_calculate_mixing_ratio(temperature, pressure)

Function to compute the mixing ratio given temperature and pressure.

Parameters:

• temperature (iris.cube.Cube) – Cube of air temperature (K).
• pressure (iris.cube.Cube) – Cube of air pressure (Pa).

Returns

mixing_ratio (iris.cube.Cube):

Cube of mixing ratios.

Method from referenced documentation. Note that EARTH_REPSILON is simply given as an unnamed constant in the reference (0.62198).

References

ASHRAE Fundamentals handbook (2005) Equation 22, 24, p6.8

calculate_wet_bulb_temperature(temperature, relative_humidity, pressure)

Perform the calculation of wet bulb temperatures. A Newton iterator is used to minimise the gradient of enthalpy against temperature.

Parameters:

• temperature (iris.cube.Cube) – Cube of air temperatures (K).
• relative_humidity (iris.cube.Cube) – Cube of relative humidities (%, converted to fractional).
• pressure (iris.cube.Cube) – Cube of air pressures (Pa).

Returns:

Cube of wet bulb temperature (K).

Return type:

wbt (iris.cube.Cube)

static check_range(cube, low, high)

Function to wrap functionality for throwing out temperatures too low or high for a method to use safely.

Parameters:

• cube (iris.cube.Cube) – A cube of temperature.
• low (int or float) – Lowest allowable temperature for check
• high (int or float) – Highest allowable temperature for check

Raises:

UserWarning – If any of the values in cube.data are outside the bounds set by the low and high variables.

lookup_svp(temperature)

Looks up a value for the saturation vapour pressure of water vapour using the temperature and a table of values. These tabulated values have been calculated using the utilties.ancillary_creation SaturatedVapourPressureTable plugin that uses the Goff-Gratch method.

Parameters:temperature (iris.cube.Cube) – A cube of air temperatures (K). Returns:A cube of saturated vapour pressures (Pa). Return type:svp (iris.cube.Cube)

static pressure_correct_svp(svp, temperature, pressure)

Convert saturated vapour pressure in a pure water vapour system into the saturated vapour pressure in air.

Method from referenced dcumentation.

References

Atmosphere-Ocean Dynamics, Adrian E. Gill, International Geophysics Series, Vol. 30; Equation A4.7.

Parameters:

• svp (iris.cube.Cube) – A cube of saturated vapour pressures (Pa).
• temperature (iris.cube.Cube) – A cube of air temperatures (K, converted to Celsius).
• pressure (iris.cube.Cube) – Cube of pressure (Pa).

Returns:

The input cube of saturated vapour pressure of air (Pa) is modified by the pressure correction.

Return type:

svp (iris.cube.Cube)

process(temperature, relative_humidity, pressure)

Call the calculate_wet_bulb_temperature function to calculate wet bulb temperatures. This process function splits input cubes over vertical levels to mitigate memory issues when trying to operate on multi-level data.

Parameters:

• temperature (iris.cube.Cube) – Cube of air temperatures (K).
• relative_humidity (iris.cube.Cube) – Cube of relative humidities (%, converted to fractional).
• pressure (iris.cube.Cube) – Cube of air pressures (Pa).

Returns:

Cube of wet bulb temperature (K).

Return type:

wet_bulb_temperature (iris.cube.Cube)

class improver.psychrometric_calculations.psychrometric_calculations.WetBulbTemperatureIntegral(precision=0.005, coord_name_to_integrate='height', start_point=None, end_point=None, direction_of_integration='negative')

Bases: object

Calculate a wet-bulb temperature integral.

__init__(precision=0.005, coord_name_to_integrate='height', start_point=None, end_point=None, direction_of_integration='negative')

Initialise class.

Keyword Arguments:  

• precision (float) – The precision to which the Newton iterator must converge before returning wet bulb temperatures.
• coord_name_to_integrate (string) – Name of the coordinate to be integrated.
• start_point (float or None) – Point at which to start the integration. Default is None. If start_point is None, integration starts from the first available point.
• end_point (float or None) – Point at which to end the integration. Default is None. If end_point is None, integration will continue until the last available point.
• direction_of_integration (string) – Description of the direction in which to integrate. Options are ‘positive’ or ‘negative’. ‘positive’ corresponds to the values within the array increasing as the array index increases. ‘negative’ corresponds to the values within the array decreasing as the array index increases.

process(temperature, relative_humidity, pressure)

Calculate the wet bulb temperature integral by firstly calculating the wet bulb temperature from the inputs provided, and then calculating the vertical integral of the wet bulb temperature.

Parameters:

• temperature (iris.cube.Cube) – Cube of air temperatures (K).
• relative_humidity (iris.cube.Cube) – Cube of relative humidities (%, converted to fractional).
• pressure (iris.cube.Cube) – Cube of air pressures (Pa).

Returns:

tuple containing

wet_bulb_temperature (iris.cube.Cube) - Cube on wet bulb temperatures on height levels (celsius)

wet_bulb_temperature_integral (iris.cube.Cube) - Cube of wet bulb temperature integral (Kelvin-metres).

Return type:

(tuple)