pycontrails.models.cocipgrid.CocipGrid

class pycontrails.models.cocipgrid.CocipGrid(met, rad, params=None, **params_kwargs)

Bases: Model

Run CoCiP simulation on a grid.

See eval() for a description of model evaluation source parameters.

Parameters:

• met (MetDataset) – CoCiP-specific met data to interpolate against

• rad (MetDataset) – CoCiP-specific radiation data to interpolate against

• params (dict[str, Any] | None, optional) – Override CocipGridParams defaults. Most notably, the model is highly dependent on the parameter dt_integration. Memory usage is also affected by parameters met_slice_dt and target_split_size.

• **params_kwargs (Any) – Override CocipGridParams defaults with arbitrary keyword arguments.

Notes

• If rad contains accumulated radiative fluxes, differencing to obtain time-averaged fluxes will reduce the time coverage of rad by half a forecast step. A warning will be produced during eval() if the time coverage of rad (after differencing) is too short given the model evaluation parameters. If this occurs, provide an additional step of radiation data at the start or end of rad.

References

• [Schumann et al., 2011]

• [Schumann et al., 2012]

See also

CocipGridParams, Cocip, wake_vortex, contrail_properties, radiative_forcing, humidity_scaling, Emissions, sac, tau_cirrus

__init__(met, rad, params=None, **params_kwargs)

Methods

__init__(met, rad[, params])
create_source(level, time[, longitude, ...])	Shortcut to create a MetDataset source from coordinate arrays.
downselect_met()	Downselect met domain to the max/min bounds of source.
ecmwf_met_variables()	Return an ECMWF-specific list of required meteorology variables.
ecmwf_rad_variables()	Return an ECMWF-specific list of required radiation variables.
eval([source])	Run CoCiP simulation on a 4d coordinate grid or arbitrary set of 4d points.
generic_met_variables()	Return a model-agnostic list of required meteorology variables.
generic_rad_variables()	Return a model-agnostic list of required radiation variables.
get_data_param(other, key[, default, set_attr])	Get data from other source-compatible object with default set by model parameter key.
get_source_param(key[, default, set_attr])	Get source data with default set by parameter key.
gfs_met_variables()	Return a GFS-specific list of required meteorology variables.
gfs_rad_variables()	Return a GFS-specific list of required radiation variables.
require_met()	Ensure that met is a MetDataset.
require_source_type(type_)	Ensure that source is type_.
set_source([source])	Attach original or copy of input source to source.
set_source_met([optional, variable])	Ensure or interpolate each required met_variables on source .
transfer_met_source_attrs([source])	Transfer met source metadata from met to source.
update_params([params])	Update model parameters on params.

Attributes

contrail
contrail_list	Artifacts attached when parameter verbose_outputs_evolution is True These allow for some additional information and parity with the approach taken by Cocip.
rad
timesteps
hash	Generate a unique hash for model instance.
interp_kwargs	Shortcut to create interpolation arguments from params.
long_name
met	Met data is not optional
met_required	Require meteorology is not None on __init__()
met_variables	Required meteorology pressure level variables.
name
params	Instantiated model parameters, in dictionary form
processed_met_variables	Set of required parameters if processing already complete on met input.
rad_variables
source	Last evaluated input source
source_time	Return the time array of the source data.
optional_met_variables	Optional meteorology variables

contrail

contrail_list

Artifacts attached when parameter verbose_outputs_evolution is True These allow for some additional information and parity with the approach taken by Cocip.

static create_source(level, time, longitude=None, latitude=None, lon_step=1.0, lat_step=1.0)

Shortcut to create a MetDataset source from coordinate arrays.

Changed in version 0.54.3: By default, the returned latitude values now extend to the poles.

Parameters:

• level (npt.NDArray[np.floating] | list[float] | float) – Pressure levels for gridded cocip. To avoid interpolating outside of the passed met and rad data, this parameter should avoid the extreme values of the met and rad levels. If met is already defined, a good choice for level is met.data['level'].values[1: -1].

• time (npt.NDArray[np.datetime64] | list[np.datetime64] | np.datetime64) – One or more time values for gridded cocip.

• longitude (npt.NDArray[np.floating] | list[float] | None, optional) – Longitude array, by default None. If not specified, values of lon_step and lat_step are used to define longitude and latitude.

• latitude (npt.NDArray[np.floating] | list[float] | None, optional) – Latitude array, by default None. If not specified, values of lon_step and lat_step are used to define longitude and latitude.

• lon_step (float, optional) – Longitude resolution, by default 1.0. Only used if parameter longitude not specified.

• lat_step (float, optional) – Latitude resolution, by default 1.0. Only used if parameter latitude not specified.

Returns:

MetDataset – MetDataset that can be used as source input to CocipGrid.eval(source=...)()

See also

MetDataset.from_coords()

default_params

alias of CocipGridParams

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

classmethod ecmwf_rad_variables()

Return an ECMWF-specific list of required radiation variables.

Returns:

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

eval(source=None, **params)

Run CoCiP simulation on a 4d coordinate grid or arbitrary set of 4d points.

If the params verbose_outputs_evolution is True, the model holds contrail_list and contrail attributes for viewing intermediate artifacts. If source data is large, these intermediate vectors may consume substantial memory.

Changed in version 0.25.0: No longer explicitly support Flight as a source. Any flight source will be viewed as a GeoVectorDataset. In order to evaluate CoCiP predictions over a flight trajectory, it is best to use the Cocip model. It’s also possible to pre-compute segment azimuth and true airspeed before passing the flight trajectory in here.

Parameters:

• source (GeoVectorDataset | MetDataset | None) – Input GeoVectorDataset or MetDataset. If None, a NotImplementedError is raised. If any subclass of GeoVectorDataset is passed (e.g., Flight), the additional structure is forgotten and the model is evaluated as if it were a GeoVectorDataset. Additional variables may be passed as source data or attrs. These include:

  • aircraft_type: This overrides any value in params. Must be included in the source attrs (not data).

  • fuel_flow, engine_efficiency, true_airspeed, wingspan, aircraft_mass: These override any value in params.

  • azimuth: This overrides any value in params.

  • segment_length: This overrides any value in params.

• **params (Any) – Overwrite model parameters before eval

Returns:

GeoVectorDataset | MetDataset – CoCiP predictions for each point in source. Output data contains variables contrail_age and ef_per_m. Additional variables specified by the model params verbose_outputs_formation are also included.

Raises:

NotImplementedError – If source is None

Notes

At a high level, the model is broken down into the following steps:

• Convert any MetDataset source to GeoVectorDataset.

• Split the source into chunks of size params["target_split_size"].

• For each timestep in timesteps:

  • Generate any new waypoints from the source data. Calculate aircraft performance and run the CoCiP downwash routine over the new waypoints.

  • For each “active” contrail (i.e., a contrail that has been initialized but has not yet reach its end of life), evolve the contrail forward one step. Filter any waypoint that has reached its end of life.

• Aggregate contrail age and energy forcing predictions to a single output variable to return.

classmethod generic_met_variables()

Return a model-agnostic list of required meteorology variables.

Returns:

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

classmethod generic_rad_variables()

Return a model-agnostic list of required radiation 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

classmethod gfs_rad_variables()

Return a GFS-specific list of required radiation 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.

long_name = 'Gridded Contrail Cirrus Prediction Model'

met

Met data is not optional

met_required = True

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.'), MetVariable(short_name='u', standard_name='eastward_wind', long_name='Eastward Wind', level_type='isobaricInhPa', ecmwf_id=131, grib1_id=33, grib2_id=(0, 2, 2), units='m s**-1', amip='ua', description='"Eastward" indicates a vector component which is positive when directed eastward (negative westward). Wind is defined as a two-dimensional (horizontal) air velocity vector, with no vertical component.'), MetVariable(short_name='v', standard_name='northward_wind', long_name='Northward Wind', level_type='isobaricInhPa', ecmwf_id=132, grib1_id=34, grib2_id=(0, 2, 3), units='m s**-1', amip='va', description='"Northward" indicates a vector component which is positive when directed northward (negative southward). Wind is defined as a two-dimensional (horizontal) air velocity vector, with no vertical component.'), MetVariable(short_name='w', standard_name='lagrangian_tendency_of_air_pressure', long_name='Vertical Velocity (omega)', level_type='isobaricInhPa', ecmwf_id=135, grib1_id=39, grib2_id=(0, 2, 8), units='Pa s**-1', amip='wap', description='The Lagrangian tendency of air pressure, often called "omega", plays the role of the upward component of air velocity when air pressure is being used as the vertical coordinate. If the vertical air velocity is upwards, it is negative when expressed as a tendency of air pressure; downwards is positive. Air pressure is the force per unit area which would be exerted when the moving gas molecules of which the air is composed strike a theoretical surface of any orientation.'), (MetVariable(short_name='cli', standard_name='mass_fraction_of_cloud_ice_in_air', long_name='Mass fraction of cloud ice in air', level_type='isobaricInhPa', ecmwf_id=None, grib1_id=None, grib2_id=None, units='kg kg**-1', amip='cli', description='The mass fraction of cloud ice in moist air.'), MetVariable(short_name='ciwc', standard_name='specific_cloud_ice_water_content', long_name='Specific cloud ice water content', level_type='isobaricInhPa', ecmwf_id=247, grib1_id=None, grib2_id=(0, 1, 84), units='kg kg**-1', amip=None, description="This parameter is the mass of cloud ice particles per kilogram of the total mass of moist air. The 'total mass of moist air' is the sum of the dry air, water vapour, cloud liquid, cloud ice, rain and falling snow. This parameter represents the average value for a grid box."), MetVariable(short_name='icmr', standard_name='ice_water_mixing_ratio', long_name='Cloud ice water mixing ratio', level_type='isobaricInhPa', ecmwf_id=260019, grib1_id=None, grib2_id=(0, 1, 23), units='kg kg**-1', amip=None, description='This parameter is the mass of cloud ice particles per kilogram of the total mass of dry 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 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.

name = 'contrail_grid'

optional_met_variables

Optional meteorology variables

params

Instantiated model parameters, in dictionary form

processed_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.'), MetVariable(short_name='u', standard_name='eastward_wind', long_name='Eastward Wind', level_type='isobaricInhPa', ecmwf_id=131, grib1_id=33, grib2_id=(0, 2, 2), units='m s**-1', amip='ua', description='"Eastward" indicates a vector component which is positive when directed eastward (negative westward). Wind is defined as a two-dimensional (horizontal) air velocity vector, with no vertical component.'), MetVariable(short_name='v', standard_name='northward_wind', long_name='Northward Wind', level_type='isobaricInhPa', ecmwf_id=132, grib1_id=34, grib2_id=(0, 2, 3), units='m s**-1', amip='va', description='"Northward" indicates a vector component which is positive when directed northward (negative southward). Wind is defined as a two-dimensional (horizontal) air velocity vector, with no vertical component.'), MetVariable(short_name='w', standard_name='lagrangian_tendency_of_air_pressure', long_name='Vertical Velocity (omega)', level_type='isobaricInhPa', ecmwf_id=135, grib1_id=39, grib2_id=(0, 2, 8), units='Pa s**-1', amip='wap', description='The Lagrangian tendency of air pressure, often called "omega", plays the role of the upward component of air velocity when air pressure is being used as the vertical coordinate. If the vertical air velocity is upwards, it is negative when expressed as a tendency of air pressure; downwards is positive. Air pressure is the force per unit area which would be exerted when the moving gas molecules of which the air is composed strike a theoretical surface of any orientation.'), MetVariable(short_name='tau_cirrus', standard_name='tau_cirrus', long_name='Cirrus optical depth', level_type=None, ecmwf_id=None, grib1_id=None, grib2_id=None, units='dimensionless', amip=None, description=None))

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

rad

rad_variables = ((MetVariable(short_name='rst', standard_name='toa_net_downward_shortwave_flux', long_name='TOA net downward shortwave flux', level_type='nominalTop', ecmwf_id=None, grib1_id=None, grib2_id=None, units='W m**-2', amip='rst', description='"shortwave" means shortwave radiation. "toa" means top of atmosphere. "Downward" indicates a vector component which is positive when directed downward (negative upward). Net downward radiation is the difference between radiation from above (downwelling) and radiation from below (upwelling). In accordance with common usage in geophysical disciplines, "flux" implies per unit area, called "flux density" in physics.'), MetVariable(short_name='tsr', standard_name='top_net_solar_radiation', long_name='Top of atmosphere net solar (shortwave) radiation', level_type='nominalTop', ecmwf_id=178, grib1_id=None, grib2_id=(0, 4, 1), units='J m**-2', amip=None, description="This parameter is the incoming solar radiation (also known as shortwave radiation) minus the outgoing solar radiation at the top of the atmosphere. It is the amount of radiation passing through a horizontal plane. The incoming solar radiation is the amount received from the Sun. The outgoing solar radiation is the amount reflected and scattered by the Earth's atmosphere and surfaceSee https://www.ecmwf.int/sites/default/files/elibrary/2015/18490-radiation-quantities-ecmwf-model-and-mars.pdf"), MetVariable(short_name='suswrf', standard_name='toa_upward_shortwave_flux', long_name='Top of atmosphere upward shortwave radiation', level_type='nominalTop', ecmwf_id=None, grib1_id=None, grib2_id=(0, 4, 193), units='W m**-2', amip=None, description='This parameter is the outgoing shortwave (solar) radiation at the nominal top of the atmosphere.')), (MetVariable(short_name='rlut', standard_name='toa_outgoing_longwave_flux', long_name='TOA outgoing longwave_flux', level_type='nominalTop', ecmwf_id=None, grib1_id=None, grib2_id=None, units='W m**-2', amip='rlut', description='"longwave" means longwave radiation. "toa" means top of atmosphere. The TOA outgoing longwave flux is the upwelling thermal radiative flux, often called the "outgoing longwave radiation" or "OLR". In accordance with common usage in geophysical disciplines, "flux" implies per unit area, called "flux density" in physics.'), MetVariable(short_name='ttr', standard_name='top_net_thermal_radiation', long_name='Top of atmosphere net thermal (longwave) radiation', level_type='nominalTop', ecmwf_id=179, grib1_id=None, grib2_id=(0, 5, 5), units='J m**-2', amip=None, description='The thermal (also known as terrestrial or longwave) radiation emitted to space at the top of the atmosphere is commonly known as the Outgoing Longwave Radiation (OLR). The top net thermal radiation (this parameter) is equal to the negative of OLR.See https://www.ecmwf.int/sites/default/files/elibrary/2015/18490-radiation-quantities-ecmwf-model-and-mars.pdf'), MetVariable(short_name='sulwrf', standard_name='toa_upward_longwave_flux', long_name='Top of atmosphere upward longwave radiation', level_type='nominalTop', ecmwf_id=None, grib1_id=None, grib2_id=(0, 5, 193), units='W m**-2', amip=None, description='This parameter is the outgoing longwave (thermal) radiation at the nominal top of the atmosphere.')))

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

Last evaluated input source

property source_time

Return the time array of the source data.

timesteps

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.