pycontrails.models.sac

Schmidt-Appleman criteria (SAC).

Functions

T_critical_sac(T_LM, relative_humidity, G[, ...])

Estimate temperature threshold for persistent contrail formation.

T_sat_liquid(G)

Calculate temperature at which liquid saturation curve has slope G.

T_sat_liquid_high_accuracy(G[, maxiter])

Calculate temperature at which liquid saturation curve has slope G.

rh_critical_sac(air_temperature, T_sat_liquid, G)

Calculate critical relative humidity threshold of contrail formation.

sac(rh, rh_crit_sac)

Points at which the Schmidt-Appleman Criteria is satisfied.

slope_mixing_line(specific_humidity, ...)

Calculate the slope of the mixing line in a temperature-humidity diagram.

Classes

SAC([met, params])

Determine points where Schmidt-Appleman Criteria is satisfied.

SACParams([copy_source, ...])

Parameters for SAC.
class pycontrails.models.sac.SAC(met=None, params=None, **params_kwargs)

Bases: Model

Determine points where Schmidt-Appleman Criteria is satisfied.

Parameters:

  • met (MetDataset) – Dataset containing “air_temperature”, “specific_humidity” variables.

  • params (dict[str, Any], optional) – Override SACParams with dictionary.

  • **params_kwargs – Override SACParams with keyword arguments.

default_params

alias of SACParams

downselect_met()

Downselect met domain to the max/min bounds of source.

Override this method if special handling is needed in met down-selection.

  • source must be defined before calling downselect_met().

  • This method copies and re-assigns met using met.copy() to avoid side-effects.

Raises:
eval(source=None, **params)

Evaluate the Schmidt-Appleman criteria 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 “sac” 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 where SAC is satisfied, 0 everywhere else. Returns np.nan if interpolating outside meteorology grid.

get_source_param(key, default=<object object>, *, set_attr=True)

Get source data with default set by parameter key.

Retrieves data with the following hierarchy:

  1. source.data[key]. Returns np.ndarray | xr.DataArray.

  2. source.attrs[key]

  3. params[key]

  4. default

In case 3., the value of params[key] is attached to source.attrs[key].

Parameters:

  • key (str) – Key to retrieve

  • default (Any, optional) – Default value if key is not found.

  • set_attr (bool, optional) – If True (default), set source.attrs[key] to params[key] if found. This allows for better post model evaluation tracking.

Returns:

Any – Value(s) found for key in source data, source attrs, or model params

Raises:

KeyError – Raises KeyError if key is not found in any location and default is not provided.

See also

-

property hash

Generate a unique hash for model instance.

Returns:

str – Unique hash for model instance (sha1)

property interp_kwargs

Shortcut to create interpolation arguments from params.

The output of this is useful for passing to interpolate_met().

Returns:

dict[str, Any] – Dictionary with keys

  • ”method”

  • ”bounds_error”

  • ”fill_value”

  • ”localize”

  • ”use_indices”

  • ”q_method”

as determined by params.

long_name = 'Schmidt-Appleman contrail formation criteria'
met

Meteorology data

met_required = False

Require meteorology is not None on __init__()

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 = 'sac'
optional_met_variables

Optional meteorology variables

params

Instantiated model parameters, in dictionary form

processed_met_variables

Set of required parameters if processing already complete on met input.

require_met()

Ensure that met is a MetDataset.

Returns:

MetDataset – Returns reference to met. This is helpful for type narrowing met when meteorology is required.

Raises:

ValueError – Raises when met is None.

require_source_type(type_)

Ensure that source is type_.

Returns:

_Source – Returns reference to source. This is helpful for type narrowing source to specific type(s).

Raises:

ValueError – Raises when source is not _type_.

set_source(source=None)

Attach original or copy of input source to source.

Parameters:

source (MetDataset | GeoVectorDataset | Flight | Iterable[Flight] | None) – Parameter source passed in eval(). If None, an empty MetDataset with coordinates like met is set to source.

See also

-

meth:eval

set_source_met(optional=False, variable=None)

Ensure or interpolate each required met_variables on source .

For each variable in met_variables, check source for data variable with the same name.

For GeoVectorDataset sources, try to interpolate met if variable does not exist.

For MetDataset sources, try to get data from met if variable does not exist.

Parameters:
Raises:
source

Data evaluated in model

transfer_met_source_attrs(source=None)

Transfer met source metadata from met to source.

update_params(params=None, **params_kwargs)

Update model parameters on params.

Parameters:

  • params (dict[str, Any], optional) – Model parameters to update, as dictionary. Defaults to {}

  • **params_kwargs (Any) – Override keys in params with keyword arguments.

class pycontrails.models.sac.SACParams(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=(np.timedelta64(0, 'h'), np.timedelta64(0, 'h')), engine_efficiency=0.3, fuel=<factory>, humidity_scaling=None)

Bases: ModelParams

Parameters for SAC.

as_dict()

Convert object to dictionary.

We use this method instead of dataclasses.asdict to use a shallow/unrecursive copy. This will return values as Any instead of dict.

Returns:

dict[str, Any] – Dictionary version of self.

copy_source = True

Copy input source data on eval

downselect_met = True

Downselect input MetDataset` to region around source.

engine_efficiency = 0.3

Jet engine efficiency, [\(0 - 1\)]

fuel

Fuel type. Overridden by Fuel provided on input source attributes

humidity_scaling = None

Humidity scaling

interpolation_bounds_error = False

If True, points lying outside interpolation will raise an error

interpolation_fill_value = nan

Used for outside interpolation value if interpolation_bounds_error is False

interpolation_localize = False

Experimental. See pycontrails.core.interpolation.

interpolation_method = 'linear'

Interpolation method. Supported methods include “linear”, “nearest”, “slinear”, “cubic”, and “quintic”. See scipy.interpolate.RegularGridInterpolator for the description of each method. Not all methods are supported by all met grids. For example, the “cubic” method requires at least 4 points per dimension.

interpolation_q_method = None

Experimental. Alternative interpolation method to account for specific humidity lapse rate bias. Must be one of None, "cubic-spline", or "log-q-log-p". If None, no special interpolation is used for specific humidity. The "cubic-spline" method applies a custom stretching of the met interpolation table to account for the specific humidity lapse rate bias. The "log-q-log-p" method interpolates in the log of specific humidity and pressure, then converts back to specific humidity. Only used by models calling to interpolate_met().

interpolation_use_indices = False

Experimental. See pycontrails.core.interpolation.

met_latitude_buffer = (0.0, 0.0)

Met latitude buffer for input to Flight.downselect_met(), in WGS84 coordinates. Only applies when downselect_met is True.

met_level_buffer = (0.0, 0.0)

Met level buffer for input to Flight.downselect_met(), in [\(hPa\)]. Only applies when downselect_met is True.

met_longitude_buffer = (0.0, 0.0)

Met longitude buffer for input to Flight.downselect_met(), in WGS84 coordinates. Only applies when downselect_met is True.

met_time_buffer = (np.timedelta64(0,'h'), np.timedelta64(0,'h'))

Met time buffer for input to Flight.downselect_met() Only applies when downselect_met is True.

verify_met = True

Call _verify_met() on model instantiation.

pycontrails.models.sac.T_critical_sac(T_LM, relative_humidity, G, maxiter=10)

Estimate temperature threshold for persistent contrail formation.

This quantity is defined as T_LC in Schumann (see reference below). Equation (11) of this paper implicitly defines T_LC as the solution to the equation

T_LC = T_LM - (e_L(T_LM) - rh * e_L(T_LC)) / G

For relative humidity above 0.999, the corresponding entry from T_LM is returned (page 10, top of the right-hand column). Otherwise, the solution to the equation above is approximated via Newton’s method.

Parameters:
Returns:

ArrayLike – Critical temperature threshold values.

References

pycontrails.models.sac.T_sat_liquid(G)

Calculate temperature at which liquid saturation curve has slope G.

Parameters:

G (ArrayLike) – Slope of the mixing line in a temperature-humidity diagram.

Returns:

ArrayLike – Maximum threshold temperature for 100% relative humidity with respect to liquid, [\(K\)]. This can also be interpreted as the temperature at which the liquid saturation curve has slope G.

References

See also

T_sat_liquid_high_accuracy()

Notes

Defined (using notation T_LM) in [Schumann, 1996] in the first full paragraph on page 10 as

for T = T_LC, the mixing line just touches [is tangent to] the saturation curve. See equation (10).

The formula used here is taken from equation (31).

pycontrails.models.sac.T_sat_liquid_high_accuracy(G, maxiter=5)

Calculate temperature at which liquid saturation curve has slope G.

The function T_sat_liquid() gives a first order approximation to equation (10) of the Schumann paper referenced below. This function uses Newton’s method to compute the numeric solution to (10).

Parameters:

  • G (ArrayLike) – Slope of the mixing line

  • maxiter (int, optional) – Passed into scipy.optimize.newton(). Because T_sat_liquid is already fairly accurate, few iterations are needed for Newton’s method to converge. By default, 5.

Returns:

ArrayLike – Maximum threshold temperature for 100% relative humidity with respect to liquid, [\(K\)].

References

See also

T_sat_liquid_high()

pycontrails.models.sac.rh_critical_sac(air_temperature, T_sat_liquid, G)

Calculate critical relative humidity threshold of contrail formation.

Parameters:

  • air_temperature (ArrayLike) – A sequence or array of temperature values, [\(K\)]

  • T_sat_liquid (ArrayLike) – Maximum threshold temperature for 100% relative humidity with respect to liquid, [\(K\)]

  • G (ArrayLike) – Slope of the mixing line in a temperature-humidity diagram.

Returns:

ArrayLike – Critical relative humidity of contrail formation, [\([0 - 1]\)]

References

pycontrails.models.sac.sac(rh, rh_crit_sac)

Points at which the Schmidt-Appleman Criteria is satisfied.

Parameters of type ArrayLike must have compatible shapes.

Parameters:

  • rh (ArrayLike) – Relative humidity values

  • rh_crit_sac (ArrayLike) – Critical relative humidity threshold of contrail formation

Returns:

ArrayLike – SAC state of each point indexed by the ArrayLike parameters. Returned array has floating dtype with values

  • 0.0 signifying SAC fails

  • 1.0 signifying SAC holds

NaN entries of parameters propagate into the returned array.

pycontrails.models.sac.slope_mixing_line(specific_humidity, air_pressure, engine_efficiency, ei_h2o, q_fuel)

Calculate the slope of the mixing line in a temperature-humidity diagram.

This quantity is often notated with G in the literature.

Parameters:

  • specific_humidity (ArrayLike) – A sequence or array of specific humidity values, [\(kg_{H_{2}O} \ kg_{air}\)]

  • air_pressure (ArrayLike) – A sequence or array of atmospheric pressure values, [\(Pa\)].

  • engine_efficiency (float | ArrayLike) – Engine efficiency, [\(0 - 1\)]

  • ei_h2o (float) – Emission index of water vapor, [\(kg \ kg^{-1}\)]

  • q_fuel (float) – Specific combustion heat of fuel combustion, [\(J \ kg^{-1} \ K^{-1}\)]

Returns:

ArrayLike – Slope of the mixing line in a temperature-humidity diagram, [\(Pa \ K^{-1}\)]