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

• [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.
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

rad
timesteps
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.
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.

Parameters:

• level (level: npt.NDArray[np.float64] | 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.float64] | 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. To avoid model degradation at the poles, latitude values are expected to be between -80 and 80 degrees.

• 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

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.

long_name = 'Gridded Contrail Cirrus Prediction Model'

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'

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='uswrf', 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='ulwrf', 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.')))

property source_time

Return the time array of the source data.

timesteps