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, rad (MetDataset) – CoCiP-specific met data to interpolate against

  • params (dict[str, Any], 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.

  • param_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

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.

eval([source])

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

get_source_param(key[, default, set_attr])

Get source data with default set by parameter key.

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 (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, latitude (npt.NDArray[np.floating] | list[float], optional) – Longitude and latitude arrays, by default None. If not specified, values of lon_step and lat_step are used to define longitude and latitude.

  • lon_step, lat_step (float, optional) – Longitude and latitude resolution, by default 1.0. Only used if parameter longitude (respective 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:
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.

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 = '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='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. Only one variable in the tuple is required.

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

-

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

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.