improver.generate_ancillaries.generate_orographic_smoothing_coefficients module
A module for creating orographic smoothing coefficients
- class OrographicSmoothingCoefficients(min_gradient_smoothing_coefficient=0.5, max_gradient_smoothing_coefficient=0.0, power=1, use_mask_boundary=False, invert_mask=False)[source]
Bases:
BasePluginClass to generate smoothing coefficients for recursive filtering based on orography gradients.
A smoothing coefficient determines how much “value” of a cell undergoing filtering is comprised of the current value at that cell and how much comes from the adjacent cell preceding it in the direction in which filtering is being applied. A larger smoothing_coefficient results in a more significant proportion of a cell’s new value coming from its neighbouring cell.
The smoothing coefficients are calculated from the orography gradient using a simple equation with the user defined value for the power:
\[\rm{smoothing\_coefficient} = \rm{gradient}^{\rm{power}}\]The resulting values are scaled between min_gradient_smoothing_coefficient and max_gradient_smoothing_coefficient to give the desired range of smoothing_coefficients. These limiting values must be greater than or equal to zero and less than or equal to 0.5.
Note that the smoothing coefficients are returned on a grid that is one cell smaller in the given dimension than the input orography, i.e. the smoothing coefficients in the x-direction are returned on a grid that is one cell smaller in x than the input. This is because the coefficients are used in both forward and backward passes of the recursive filter, so they need to be symmetric between cells in the original grid to help ensure conservation.
- __init__(min_gradient_smoothing_coefficient=0.5, max_gradient_smoothing_coefficient=0.0, power=1, use_mask_boundary=False, invert_mask=False)[source]
Initialise class.
- Parameters:
min_gradient_smoothing_coefficient (
float) – The value of recursive filter smoothing_coefficient to be used where the orography gradient is a minimum. Generally this number will be larger than the max_gradient_smoothing_coefficient as quantities are likely to be smoothed more across flat terrain.max_gradient_smoothing_coefficient (
float) – The value of recursive filter smoothing_coefficient to be used where the orography gradient is a maximum. Generally this number will be smaller than the min_gradient_smoothing_coefficient as quantities are likely to be smoothed less across complex terrain.power (
float) – The power to be used in the smoothing_coefficient equationuse_mask_boundary (
bool) – A mask can be provided to this plugin to define a region in which smoothing coefficients are set to zero, i.e. no smoothing. If this option is set to True then rather than the whole masked region being set to zero, only the cells that mark the transition from masked to unmasked will be set to zero. The primary purpose for this is to prevent smoothing across land-sea boundaries.invert_mask (
bool) – By default, if a mask is provided and use_mask_boundary is False, all the smoothing coefficients corresponding to a mask value of 1 will be zeroed. Setting invert_mask to True reverses this behaviour such that mask values of 0 set the points to be zeroed in the smoothing coefficients. If use_mask_boundary is True this option has no effect.
- _abc_impl = <_abc_data object>
- create_coefficient_cube(data, template, cube_name, attributes)[source]
Update metadata in smoothing_coefficients cube. Remove any time coordinates and rename.
- Parameters:
- Return type:
- Returns:
A new cube of smoothing_coefficients
- process(cube, mask=None)[source]
This creates the smoothing_coefficient cubes. It returns one for the x direction and one for the y direction. It uses the DifferenceBetweenAdjacentGridSquares plugin to calculate an average gradient across each grid square. These gradients are then used to calculate “smoothing_coefficient” arrays that are normalised between a user-specified max and min.
- Parameters:
cube (
Cube) – A 2D field of orography on the grid for which smoothing_coefficients are to be generated.mask (
Optional[Cube]) – A mask that defines where the smoothing coefficients should be zeroed. The mask must have the same spatial dimensions as the orography cube. How the mask is used to zero smoothing coefficients is determined by the plugin configuration arguments.
- Return type:
- Returns:
A cube of orography-dependent smoothing_coefficients calculated in the x direction.
A cube of orography-dependent smoothing_coefficients calculated in the y direction.
- scale_smoothing_coefficients(cubes)[source]
This scales a set of smoothing_coefficients from input cubes to range between the min_gradient_smoothing_coefficient and the max_gradient_smoothing_coefficient.
- unnormalised_smoothing_coefficients(gradient_cube)[source]
This generates initial smoothing_coefficient values from gradients using a simple power law, for which the power is set at initialisation. Using a power of 1 gives an output smoothing_coefficients_cube with values equal to the input gradient_cube.
- zero_masked(smoothing_coefficient_x, smoothing_coefficient_y, mask)[source]
Zero smoothing coefficients in regions or at boundaries defined by the provided mask. The changes are made in place to the input cubes. The behaviour is as follows:
- use_mask_boundary = True:
The edges of the mask region are used to define where smoothing coefficients should be zeroed. The zeroed smoothing coefficients are between the masked and unmasked cells of the grid on which the mask is defined.
- invert_mask = False:
All smoothing coefficients within regions for which the mask has value 1 are set to 0. The boundary cells between masked and unmasked are also set to 0. Has no effect if use_mask_boundary=True.
- invert_mask = True:
All smoothing coefficients within regions for which the mask has value 0 are set to 0. The boundary cells between masked and unmasked are also set to 0. Has no effect if use_mask_boundary=True.