credit.interp#

Functions to interpolate data to pressure and height coordinates.

Functions#

`full_state_pressure_interpolation`(, interp_fields, ...)	Interpolate the full state of the model to pressure and height coordinates.
`fast_state_interp_loop`(surface_pressure_data, ...)
`create_pressure_grid`(surface_pressure, model_a_half, ...)	Create a pressure 3D grid from a full set of vertical levels.
`create_reduced_pressure_grid`(surface_pressure, ...)	Create a pressure 3D grid using sparse vertical levels.
`geopotential_from_model_vars`(surface_geopotential, ...)	Calculate geopotential from model level data.
`interp_hybrid_to_pressure_levels`(model_var, ...[, use_log])	Interpolate to pressure levels.
`interp_pressure_to_hybrid_levels`(pressure_var, ...)	Interpolate fields on pressure levels to hybrid levels.
`interp_hybrid_to_hybrid_levels`(hybrid_var, ...)	Interpolate fields on hybrid levels to hybrid levels via pressure.
`interp_geopotential_to_pressure_levels`(geopotential, ...)	Interpolate geopotential field to pressure levels.
`interp_temperature_to_pressure_levels`(model_var, ...)	Interpolate the temperature field to pressure levels.
`interp_hybrid_to_height_agl`(model_var, ...)	Interpolate data on hybrid sigma-pressure levels to heights above ground level in meters.
`mean_sea_level_pressure`(surface_pressure_pa, ...[, ...])	Calculate the mean sea level pressure.
`mean_sea_level_pressure_simple`(surface_pressure_pa, ...)	Simpler calculation for mean sea level pressure that only requires 2D fields of pressure (Pa), temperature (K),

Module Contents#

credit.interp.full_state_pressure_interpolation(state_dataset: xarray.Dataset, surface_geopotential: numpy.ndarray, pressure_levels: numpy.ndarray = np.array([500.0, 850.0]), interp_fields: tuple[str] = ('U', 'V', 'T', 'Q'), pres_ending: str = '_PRES', height_levels: numpy.ndarray = None, height_ending: str = '_HEIGHT', temperature_var: str = 'T', q_var: str = 'Q', surface_pressure_var: str = 'SP', geopotential_var: str = 'Z', time_var: str = 'time', lat_var: str = 'latitude', lon_var: str = 'longitude', pres_var: str = 'pressure', level_var: str = 'level', height_var: str = 'height_agl', model_level_file: str = '../credit/metadata/ERA5_Lev_Info.nc', verbose: int = 1, a_model_name: str = 'a_model', b_model_name: str = 'b_model', a_half_name: str = 'a_half', b_half_name: str = 'b_half', P0: float = 1.0, pressure_3d_var: str = 'P', mslp_temp_height: float = 1000.0, use_simple_mslp: bool = False, surface_geopotential_var: str = 'geopotential_at_surface') → xarray.Dataset#

Interpolate the full state of the model to pressure and height coordinates.

Interpolate full model state variables from model levels to pressure levels and height levels. The raw CREDIT model output are on hybrid sigma-pressure vertical levels, which start as terrain following near the surface and relax to constant pressure levels aloft. The state variables for CREDIT models (and hydrostatic models more generally) are u, v, temperature, specific humidity, and surface pressure, with surface geopotential as a static variable. To perform pressure and height interpolation, the following steps happen:

Pressure is calculated on every full model level (middle of the vertical grid box) and half level (top and
bottom of the vertical grid box starting at the surface and ending at the model top of the atmospshere). This requires knowing the a and b coefficients for the model levels.
Geopotential on each hybrid sigma-pressure level is calculated from surface geopotential, pressure, temperature, and specific humidity as a vertical integral calculation. The calculation is sensitive to numerical precision, so data are cast to float64 before calling the geopotential calculation.
Interpolation is done from hybrid sigma-pressure levels to fixed pressure levels. Everything is interpolated
linearly with log(pressure) as the x coordinate. For pressure levels below ground (where pressure of level > surface pressure), special extrapolation routines are done for temperature and geopotential while constant extrapolation is assumed for u, v, and q.
Interpolation to height above ground level is also performed at the end. Heights are defined in meters.

Parameters:

state_dataset (xr.Dataset) – state variables being interpolated
surface_geopotential (np.ndarray) – surface geopotential levels in units m^2/s^2.
pressure_levels (np.ndarray) – pressure levels for interpolation in hPa.
interp_fields (tuple[str]) – fields to be interpolated.
pres_ending (str) – ending string to attach to pressure interpolated variables.
height_levels (np.ndarray) – height levels for interpolation to height above ground level in meters.
height_ending (str) – ending string to attach to height interpolated variables.
temperature_var (str) – temperature variable to be interpolated (units K).
q_var (str) – mixing ratio/specific humidity variable to be interpolated (units kg/kg).
surface_pressure_var (str) – surface pressure variable (units Pa).
geopotential_var (str) – geopotential variable being derived (units m^2/s^2).
time_var (str) – time coordinate
lat_var (str) – latitude coordinate
lon_var (str) – longitude coordinate
pres_var (str) – pressure coordinate
level_var (str) – name of level coordinate
height_var (str) – height coordinate
model_level_file (str) – relative path to file containing model levels.
verbose (int) – verbosity level. If verbose > 0, print progress.
a_model_name (str) – Name of A weight at level midpoints in sigma coordinate formula. ‘a_model’ by default.
b_model_name (str) – Name of B weight at level midpoints in sigma coordinate formula. ‘b_model’ by default.
a_half_name (str) – Name of A weight at level interfaces in sigma coordinate formula. ‘a_half’ by default.
b_half_name (str) – Name of B weight at level interfaces in sigma coordinate formula. ‘b_half’ by default.
P0 (float) – reference pressure if pressure needs to be scaled.
pressure_3d_var (str) – Name of the 3D pressure field derived on the model grid.
mslp_temp_height (float) – height above ground level in meters where temperature is sampled for mslp calculation.
use_simple_mslp (bool) – Whether to use the simple or complex MSLP calculation.
surface_geopotential_var (str) – Name of the unnormalized surface geopotential variable being used for MSLP calculations

Returns:

Dataset containing pressure interpolated variables.

Return type:

pressure_ds (xr.Dataset)

credit.interp.fast_state_interp_loop(surface_pressure_data, state_dict, surface_geopotential, temperature_var, q_var, interp_fields, geopotential_var, a_model, b_model, a_half_full, b_half_full, pressure_levels, pres_ending, height_ending, height_levels, pressure_3d_var, level_var, levels)#

credit.interp.create_pressure_grid(surface_pressure, model_a_half, model_b_half)#

Create a pressure 3D grid from a full set of vertical levels.

Create a 3D pressure field at model levels from the surface pressure field and the hybrid sigma-pressure coefficients from ECMWF. Conversion is pressure_3d = a + b * SP.

Parameters:

surface_pressure (np.ndarray) – (time, latitude, longitude) or (latitude, longitude) grid in units of Pa.
model_a_half (np.ndarray) – a coefficients at each model level being used in units of Pa.
model_b_half (np.ndarray) – b coefficients at each model level being used (unitness).

Returns:

3D pressure field with dimensions of surface_pressure and number of levels from model_a and model_b.

Return type:

pressure_3d

credit.interp.create_reduced_pressure_grid(surface_pressure, model_a_full, model_b_full)#

Create a pressure 3D grid using sparse vertical levels.

Create a 3D pressure field at model levels from the surface pressure field and the reduced set of hybrid sigma- pressure levels used in the CREDIT models. This function assumes that the coefficients for the full levels are being passed and then derives the half levels by taking the geometric means of the a and b coefficients on full levels. Conversion is pressure_3d = a + b * SP.

Parameters:

surface_pressure (np.ndarray) – (time, latitude, longitude) or (latitude, longitude) grid in units of Pa.
model_a_full (np.ndarray) – a coefficients at each model level being used in units of Pa.
model_b_full (np.ndarray) – b coefficients at each model level being used (unitless).

Returns:

3D pressure field with dimensions of surface_pressure and number of levels from model_a and model_b.

Return type:

pressure_3d

credit.interp.geopotential_from_model_vars(surface_geopotential, surface_pressure, temperature, specific_humidity, half_pressure)#

Calculate geopotential from model level data.

Calculate geopotential from the base state variables. Geopotential height is calculated by adding thicknesses calculated within each half-model-level to account for variations in temperature and moisture between grid cells. Note that this function is calculating geopotential in units of (m^2 s^-2) not geopential height.

To convert geopotential to geopotential height, divide geopotential by g (9.806 m s^-2).

Geopotential height is defined as the height above mean sea level. To get height above ground level, substract the surface geoptential height field from the 3D geopotential height field.

Parameters:

surface_geopotential (np.ndarray) – Surface geopotential in shape (y,x) and units m^2 s^-2.
surface_pressure (np.ndarray) – Surface pressure in shape (y, x) and units Pa
temperature (np.ndarray) – temperature in shape (levels, y, x) and units K
specific_humidity (np.ndarray) – mixing ratio in shape (levels, y, x) and units kg/kg.

Returns:

geopotential on model levels in shape (levels, y, x)

Return type:

model_geoptential (np.ndarray)

credit.interp.interp_hybrid_to_pressure_levels(model_var, model_pressure, interp_pressures, use_log=True)#

Interpolate to pressure levels.

Interpolate data field from hybrid sigma-pressure vertical coordinates to pressure levels. model_pressure and interp_pressure should have consistent units with each other.

Parameters:

model_var (np.ndarray) – 3D field on hybrid sigma-pressure levels with shape (levels, y, x).
model_pressure (np.ndarray) – 3D pressure field with shape (levels, y, x) in units Pa or hPa
interp_pressures – (np.ndarray): pressure levels for interpolation in units Pa or hPa.
use_log (bool) – If True, use the natural logarithm of the pressure as the interpolation coordinate. Otherwise, use the pressure.

Returns:

3D field on pressure levels with shape (len(interp_pressures), y, x).

Return type:

pressure_var (np.ndarray)

credit.interp.interp_pressure_to_hybrid_levels(pressure_var, pressure_levels, model_pressure, surface_pressure)#

Interpolate fields on pressure levels to hybrid levels.

Interpolate data field from hybrid sigma-pressure vertical coordinates to pressure levels. model_pressure and pressure_levels and ‘surface_pressure’ should have consistent units with each other.

Parameters:

pressure_var (np.ndarray) – 3D field on pressure levels with shape (levels, y, x).
pressure_levels (np.double) – pressure levels for interpolation in units Pa or hPa.
model_pressure (np.ndarray) – 3D pressure field with shape (levels, y, x) in units Pa or hPa
surface_pressure (np.ndarray) – pressure at the surface in units Pa or hPa.

Returns:

3D field on hybrid sigma-pressure levels with shape (model_pressure.shape[0], y, x).

Return type:

model_var (np.ndarray)

credit.interp.interp_hybrid_to_hybrid_levels(hybrid_var, hybrid_pressure, target_pressure)#

Interpolate fields on hybrid levels to hybrid levels via pressure.

Interpolate data from hybrid sigma-pressure vertical coordinates to other hybrid levels.

Parameters:

hybrid_var (np.ndarray) – 3D field on hybrid sigma-pressure levels with shape (levels, y, x).
hybrid_pressure (np.double) – pressure levels for interpolation in units Pa or hPa.
target_pressure (np.ndarray) – 3D target pressure fields with shape (levels, y, x) in units Pa or hPa

Returns:

3D field on hybrid sigma-pressure levels with shape (target_pressure.shape[0], y, x).

Return type:

model_var (np.ndarray)

credit.interp.interp_geopotential_to_pressure_levels(geopotential, model_pressure, interp_pressures, surface_pressure, surface_geopotential, temperature_k, temp_height=150)#

Interpolate geopotential field to pressure levels.

Interpolate geopotential field from hybrid sigma-pressure vertical coordinates to pressure levels. model_pressure and interp_pressure should have consistent units of hPa or Pa. Geopotential height is extrapolated below the surface based on Eq. 15 in Trenberth et al. (1993).

Parameters:

geopotential (np.ndarray) – geopotential in units m^2/s^2.
model_pressure (np.ndarray) – 3D pressure field with shape (levels, y, x) in units Pa or hPa
interp_pressures (np.ndarray) – pressure levels for interpolation in units Pa or hPa.
surface_pressure (np.ndarray) – pressure at the surface in units Pa or hPa.
surface_geopotential (np.ndarray) – geopotential at the surface in units m^2/s^2.
temperature_k (np.ndarray) – temperature in units K.
temp_height (float) – height above ground of nearest vertical grid cell.

Returns:

3D field on pressure levels with shape (len(interp_pressures), y, x).

Return type:

pressure_var (np.ndarray)

credit.interp.interp_temperature_to_pressure_levels(model_var, model_pressure, interp_pressures, surface_pressure, surface_geopotential, geopotential, temp_height=150)#

Interpolate the temperature field to pressure levels.

Interpolate temperature field from hybrid sigma-pressure vertical coordinates to pressure levels. model_pressure and interp_pressure should have consistent units of hPa or Pa. Temperature is extrapolated below the surface based on Eq. 16 in Trenberth et al. (1993).

Parameters:

model_var (np.ndarray) – 3D field on hybrid sigma-pressure levels with shape (levels, y, x).
model_pressure (np.ndarray) – 3D pressure field with shape (levels, y, x) in units Pa
interp_pressures – (np.ndarray): pressure levels for interpolation in units Pa or.
surface_pressure (np.ndarray) – pressure at the surface in units Pa or hPa.
surface_geopotential (np.ndarray) – geopotential at the surface in units m^2/s^2.
temp_height (float) – height above ground of nearest vertical grid cell.

Returns:

3D field on pressure levels with shape (len(interp_pressures), y, x).

Return type:

pressure_var (np.ndarray)

credit.interp.interp_hybrid_to_height_agl(model_var: numpy.ndarray, interp_heights_m: numpy.ndarray, geopotential: numpy.ndarray, surface_geopotential: numpy.ndarray)#

Interpolate data on hybrid sigma-pressure levels to heights above ground level in meters.

Parameters:

model_var (np.ndarray) – State variable of shape [levels, lat, lon]
interp_heights_m (np.ndarray) – 1D array of height levels in meters above ground level.
geopotential (np.ndarray) – geopotential on model levels in units of m^2/s^2.
surface_geopotential – geopotential at the surface in units of m^2/s^2.

Returns:

State variable on height above ground levels in shape [interp_heights, lat, lon].

Return type:

height_var (np.ndarray)

credit.interp.mean_sea_level_pressure(surface_pressure_pa, temperature_k, pressure_pa, surface_geopotential, geopotential, temp_height=150.0)#

Calculate the mean sea level pressure.

Calculate mean sea level pressure from surface pressure, lowest model level temperature, the pressure of the lowest model level (derived from create_pressure_grid), and surface_geopotential. This calculation is based on the procedure from Trenberth et al. (1993) implemented in CESM CAM.

Trenberth, K., J. Berry , and L. Buja, 1993: Vertical Interpolation and Truncation of Model-Coordinate, University Corporation for Atmospheric Research, https://doi.org/10.5065/D6HX19NH.

CAM implementation: ESCOMP/CAM

Parameters:

surface_pressure_pa – surface pressure in Pascals
temperature_k – Temperature at the lowest model level in Kelvin.
pressure_pa – Pressure at the lowest model level in Pascals.
surface_geopotential – Geopotential of the surface in m^2 s^-2.
geopotential – Geopotential at all levels.
temp_height – height of nearest vertical grid cell

Returns:

Mean sea level pressure in Pascals.

Return type:

mslp

credit.interp.mean_sea_level_pressure_simple(surface_pressure_pa, temperature_k, surface_geopotential)#

Simpler calculation for mean sea level pressure that only requires 2D fields of pressure (Pa), temperature (K), and surface geopotential (m ** 2 s ** -2). Based on Trenberth et al. 1993 calculation but simplified by removing the T* calculation since it seemed to only vary by about 0.2 K and requires a lot more data to compute. Trenberth, K., J. Berry , and L. Buja, 1993: Vertical Interpolation and Truncation of Model-Coordinate, University Corporation for Atmospheric Research, https://doi.org/10.5065/D6HX19NH.

Parameters:

surface_pressure_pa – surface pressure in Pascals
temperature_k – temperature in Kelvin
surface_geopotential – surface geopotential in m^2 s^-2. If you have surface height, multiply by g (9.81 m2s-2)

Returns:

mean sea level pressure in Pascals.