pycontrails.core.models

Physical model data structures.

Module Attributes

ModelInput	Model input source types
ModelOutput	Model output source types
SourceType	Model attribute source types

Functions

interpolate_gridded_specific_humidity(mda, ...)	Interpolate specific humidity against vector with experimental q_method.
interpolate_met(met, vector, met_key[, ...])	Interpolate vector against met gridded data.
raise_invalid_q_method_error(q_method)	Raise error for invalid q_method.
update_param_dict(param_dict, new_params)	Update parameter dictionary in place.

Classes

AdvectionBuffers([copy_source, ...])	Override buffers in ModelParams for advection models.
Model([met, params])	Base class for physical models.
ModelParams([copy_source, ...])	Class for constructing model parameters.

class pycontrails.core.models.AdvectionBuffers(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=(10.0, 10.0), met_latitude_buffer=(10.0, 10.0), met_level_buffer=(40.0, 40.0), met_time_buffer=(np.timedelta64(0, 'h'), np.timedelta64(0, 'h')))

Bases: ModelParams

Override buffers in ModelParams for advection models.

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.

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 = (10.0, 10.0)

Met latitude buffer [WGS84] for evolution by advection.

met_level_buffer = (40.0, 40.0)

Met level buffer [\(hPa\)] for evolution by advection.

met_longitude_buffer = (10.0, 10.0)

Met longitude [WGS84] buffer for evolution by advection.

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.

class pycontrails.core.models.Model(met=None, params=None, **params_kwargs)

Bases: ABC

Base class for physical models.

Implementing classes must implement the eval() method

default_params

Default model parameter dataclass

alias of ModelParams

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:

• ValueError – Raised if source is not defined. Raised if source is not a GeoVectorDataset.

• TypeError – Raised if met is not a MetDataset.

classmethod ecmwf_met_variables()

Return an ECMWF-specific list of required meteorology variables.

Returns:

tuple[MetVariable] – List of ECMWF-specific variants of required variables

abstract eval(source=None, **params)

Abstract method to handle evaluation.

Implementing classes should override call signature to overload source inputs and model outputs.

Parameters:

• source (ModelInput, optional) – Dataset defining coordinates to evaluate model. Defined by implementing class, but must be a subset of ModelInput. If None, met is assumed to be evaluation points.

• **params (Any) – Overwrite model parameters before evaluation.

Returns:

ModelOutput – Return type depends on implementing model

classmethod generic_met_variables()

Return a model-agnostic list of required meteorology variables.

Returns:

tuple[MetVariable] – List of model-agnostic variants of required variables

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

Get data from other source-compatible object with default set by model parameter key.

Retrieves data with the following hierarchy:

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

2. other.attrs[key]

3. params[key]

4. default

In case 3., the value of params[key] is attached to other.attrs[key] unless set_attr is set to False.

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 other data, other attrs, or model params

Raises:

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

See also

get_source_param, pycontrails.core.vector.GeoVectorDataset.get_data_or_attr

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] unless set_attr is set to False.

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

get_data_param, pycontrails.core.vector.GeoVectorDataset.get_data_or_attr

classmethod gfs_met_variables()

Return a GFS-specific list of required meteorology variables.

Returns:

tuple[MetVariable] – List of GFS-specific variants of required variables

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.

abstract property long_name

Get long name descriptor, annotated on xr.DataArray outputs.

met

Meteorology data

met_required = False

Require meteorology is not None on __init__()

met_variables

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 and the tuple must include entries for a model-agnostic variable, an ECMWF-specific variable, and a GFS-specific variable. Only one of the three variable in the tuple is required for model evaluation.

abstract property name

class`Flight`.

Type:

Get model name for use as a data key in xr.DataArray or

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

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:

• optional (bool, optional) – Include optional_met_variables

• variable (MetVariable | Sequence[MetVariable] | None, optional) – MetVariable to set, from met_variables. If None, set all variables in met_variables and optional_met_variables if optional is True.

Raises:

• ValueError – Variable does not exist and source is a MetDataset.

• KeyError – Variable not found in source or met.

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.

pycontrails.core.models.ModelInput = pycontrails.core.met.MetDataset | pycontrails.core.vector.GeoVectorDataset | pycontrails.core.flight.Flight | collections.abc.Sequence[pycontrails.core.flight.Flight] | None

Model input source types

pycontrails.core.models.ModelOutput = pycontrails.core.met.MetDataArray | pycontrails.core.met.MetDataset | pycontrails.core.vector.GeoVectorDataset | pycontrails.core.flight.Flight | list[pycontrails.core.flight.Flight]

Model output source types

class pycontrails.core.models.ModelParams(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')))

Bases: object

Class for constructing model parameters.

Implementing classes must still use the @dataclass operator.

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.

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.core.models.SourceType = pycontrails.core.met.MetDataset | pycontrails.core.vector.GeoVectorDataset | pycontrails.core.flight.Flight | pycontrails.core.fleet.Fleet

Model attribute source types

pycontrails.core.models.interpolate_gridded_specific_humidity(mda, vector, q_method, log_applied, **interp_kwargs)

Interpolate specific humidity against vector with experimental q_method.

Parameters:

• mda (MetDataArray) – MetDataArray of specific humidity.

• vector (GeoVectorDataset) – Flight or GeoVectorDataset instance

• q_method ({None, "cubic-spline", "log-q-log-p"}) – Experimental method to use for interpolating specific humidity.

• log_applied (bool) – Whether or not a log transform was applied to specific humidity.

• **interp_kwargs (Any,) – Additional keyword only arguments passed to intersect_met.

Returns:

numpy.ndarray – Interpolated values.

pycontrails.core.models.interpolate_met(met, vector, met_key, vector_key=None, *, q_method=None, **interp_kwargs)

Interpolate vector against met gridded data.

If vector_key (=``met_key`` by default) already exists, return values at vector_key.

Mutates parameter vector in place by attaching new key and returns values.

Parameters:

• met (MetDataset | None) – Met data to interpolate against

• vector (GeoVectorDataset) – Flight or GeoVectorDataset instance

• met_key (str) – Key of met variable in met.

• vector_key (str, optional) – Key of variable to attach to vector. By default, use met_key.

• q_method (str, optional) – Experimental method to use for interpolating specific humidity. See ModelParams for more information.

• **interp_kwargs (Any,) – Additional keyword only arguments passed to GeoVectorDataset.intersect_met(). For example, level=[...].

Returns:

npt.NDArray[np.floating] – Interpolated values.

Raises:

KeyError – Parameter met_key not found in met.

pycontrails.core.models.raise_invalid_q_method_error(q_method)

Raise error for invalid q_method.

Parameters:

q_method (str) – q_method to raise error for.

Raises:

ValueError – q_method is not one of None, "log-q-log-p", or "cubic-spline".

pycontrails.core.models.update_param_dict(param_dict, new_params)

Update parameter dictionary in place.

Parameters:

• param_dict (dict[str, Any]) – Active model parameter dictionary

• new_params (dict[str, Any]) – Model parameters to update, as a dictionary

Raises:

KeyError – Raises when new_params key is not found in param_dict