pycontrails.models.issr¶

Ice super-saturated regions (ISSR).

Functions

issr(air_temperature[, specific_humidity, ...])

Calculate ice super-saturated regions.

Classes

`ISSR`([met, params])	Ice super-saturated regions over a `Flight` trajectory or `MetDataset` grid.
`ISSRParams`([copy_source, ...])	Default ISSR model parameters.

class pycontrails.models.issr.ISSR(met=None, params=None, **params_kwargs)¶

Bases: Model

Ice super-saturated regions over a Flight trajectory or MetDataset grid.

This model calculates points where the relative humidity over ice is greater than 1.

Parameters:: met (MetDataset) – Dataset containing “air_temperature” and “specific_humidity” variables

Examples

>>> from datetime import datetime
>>> from pycontrails.datalib.ecmwf import ERA5
>>> from pycontrails.models.issr import ISSR
>>> from pycontrails.models.humidity_scaling import ConstantHumidityScaling

>>> # Get met data
>>> time = datetime(2022, 3, 1, 0), datetime(2022, 3, 1, 2)
>>> variables = ["air_temperature", "specific_humidity"]
>>> pressure_levels = [200, 250, 300]
>>> era5 = ERA5(time, variables, pressure_levels)
>>> met = era5.open_metdataset()

>>> # Instantiate and run model
>>> scaling = ConstantHumidityScaling(rhi_adj=0.98)
>>> model = ISSR(met, humidity_scaling=scaling)
>>> out1 = model.eval()
>>> issr1 = out1["issr"]
>>> issr1.proportion  # Get proportion of values with ice supersaturation
0.11414134603859523

>>> # Run with a lower threshold
>>> out2 = model.eval(rhi_threshold=0.95)
>>> issr2 = out2["issr"]
>>> issr2.proportion
0.146647

default_params¶: alias of ISSRParams

eval(source=None, **params)¶

Evaluate ice super-saturated regions along flight trajectory or on meteorology grid.

Changed in version 0.27.0: Humidity scaling now handled automatically. This is controlled by model parameter humidity_scaling.

Changed in version 0.48.0: If the source is a MetDataset, the returned object will also be a MetDataset. Previous the “issr” MetDataArray was returned.

Parameters:

source (GeoVectorDataset | Flight | MetDataset | None, optional) – Input GeoVectorDataset or Flight. If None, evaluates at the met grid points.
**params (Any) – Overwrite model parameters before eval

Returns:

GeoVectorDataset | Flight | MetDataset – Returns 1 in ISSR, 0 everywhere else. Returns np.nan if interpolating outside meteorology grid.

Raises:

NotImplementedError – Raises if input source is not supported.

long_name = 'Ice super-saturated regions'¶

met¶: Meteorology data

met_variables = (MetVariable(short_name='t', standard_name='air_temperature', long_name='Air Temperature', level_type='isobaricInhPa', ecmwf_id=130, grib1_id=11, grib2_id=(0, 0, 0), units='K', amip='ta', description='Air temperature is the bulk temperature of the air, not the surface (skin) temperature.'), MetVariable(short_name='q', standard_name='specific_humidity', long_name='Specific Humidity', level_type='isobaricInhPa', ecmwf_id=133, grib1_id=51, grib2_id=(0, 1, 0), units='kg kg**-1', amip='hus', description='Specific means per unit mass. Specific humidity is the mass fraction of water vapor in (moist) air.'))¶: Required meteorology pressure level variables. Each element in the list is a MetVariable or a tuple[MetVariable]. If element is a tuple[MetVariable], the variable depends on the data source. Only one variable in the tuple is required.

name = 'issr'¶

params¶: Instantiated model parameters, in dictionary form

source¶: Data evaluated in model

class pycontrails.models.issr.ISSRParams(copy_source=True, interpolation_method='linear', interpolation_bounds_error=False, interpolation_fill_value=nan, interpolation_localize=False, interpolation_use_indices=False, interpolation_q_method=None, verify_met=True, downselect_met=True, met_longitude_buffer=(0.0, 0.0), met_latitude_buffer=(0.0, 0.0), met_level_buffer=(0.0, 0.0), met_time_buffer=(numpy.timedelta64(0, 'h'), numpy.timedelta64(0, 'h')), rhi_threshold=1.0, humidity_scaling=None)¶

Bases: ModelParams

Default ISSR model parameters.

humidity_scaling = None¶: Humidity scaling

rhi_threshold = 1.0¶: RHI Threshold

pycontrails.models.issr.issr(air_temperature, specific_humidity=None, air_pressure=None, rhi=None, rhi_threshold=1.0)¶

Calculate ice super-saturated regions.

Regions where the atmospheric relative humidity over ice is greater than 1.

Parameters air_temperature, specific_humidity, air_pressure, and rhi must have compatible shapes when defined.

Either specific_humidity and air_pressure must both be provided, or rhi must be provided.

Parameters:

air_temperature (ArrayLike) – A sequence or array of temperature values, \([K]\).
specific_humidity (ArrayLike | None) – A sequence or array of specific humidity values, [\(kg_{H_{2}O} \ kg_{moist air}\)] None by default.
air_pressure (ArrayLike | None) – A sequence or array of atmospheric pressure values, [\(Pa\)]. None by default.
rhi (ArrayLike | None, optional) – A sequence of array of RHi values, if already known. If not provided, this function will compute RHi from air_temperature, specific_humidity, and air_pressure. None by default.
rhi_threshold (float, optional) – Relative humidity over ice threshold for determining ISSR state

Returns:

ArrayLike – ISSR state of each point indexed by the parameters.