pycontrails.models.cocip.Cocip¶

class pycontrails.models.cocip.Cocip(met, rad, params=None, **params_kwargs)¶

Bases: Model

Contrail Cirrus Prediction Model (CoCiP).

Published by Ulrich Schumann et. al. (DLR Institute of Atmospheric Physics) in [Schumann, 2012], [Schumann et al., 2012].

Parameters:

met (MetDataset) – Pressure level dataset containing met_variables variables. See Notes for variable names by data source.
rad (MetDataset) – Single level dataset containing top of atmosphere radiation fluxes. See Notes for variable names by data source.
params (dict[str, Any], optional) – Override Cocip model parameters with dictionary. See CocipFlightParams for model parameters.
**params_kwargs (Any) – Override Cocip model parameters with keyword arguments. See CocipFlightParams for model parameters.

Notes

Inputs

The required meteorology variables depend on the data source (e.g. ECMWF, GFS).

See met_variables and rad_variables for the list of required variables to the met and rad parameters, respectively. When an item in one of these arrays is a tuple, variable keys depend on data source.

The current list of required variables (labelled by "standard_name"):

Variable keys for pressure level data¶
Parameter	ECMWF	GFS
Air Temperature	`air_temperature`	`air_temperature`
Specific Humidity	`specific_humidity`	`specific_humidity`
Eastward wind	`eastward_wind`	`eastward_wind`
Northward wind	`northward_wind`	`northward_wind`
Vertical velocity	`lagrangian_tendency_of_air_pressure`	`lagrangian_tendency_of_air_pressure`
Ice water content	`specific_cloud_ice_water_content`	`ice_water_mixing_ratio`

Variable keys for single-level radiation data¶
Parameter	ECMWF	GFS
Top solar radiation	`top_net_solar_radiation`	`toa_upward_shortwave_flux`
Top thermal radiation	`top_net_thermal_radiation`	`toa_upward_longwave_flux`

Modifications

This implementation differs from original CoCiP (Fortran) implementation in a few places:

This model uses aircraft performance and emissions models to calculate nvPM, fuel flow, and overall propulsion efficiency, if not already provided.
As described in [Teoh et al., 2022], this implementation sets the initial ice particle activation rate to be a function of the difference between the ambient temperature and the critical SAC threshold temperature. See pycontrails.models.sac.T_critical_sac().
Isobaric heat capacity calculation. The original model uses a constant value of 1004 \(J \ kg^{-1} \ K^{-1}\), whereas this model calculates isobaric heat capacity as a function of specific humidity. See pycontrails.physics.thermo.c_pm().
Solar direct radiation. The original algorithm uses ECMWF radiation variable tisr (top incident solar radiation) as solar direct radiation value. This implementation calculates the theoretical solar direct radiation at any arbitrary point in the atmosphere. See pycontrails.physics.geo.solar_direct_radiation().
Segment angle. The segment angle calculations for flights and contrail segments have been updated to use more precise spherical geometry instead of a triangular approximation. As the triangle approaches zero, the two calculations agree. See pycontrails.physics.geo.segment_angle().
Integration. This implementation consistently uses left-Riemann sums in the time integration of contrail segments.
Segment length ratio. Instead of taking a geometric mean between contrail segments before/after advection, a simple ratio is computed. See contrail_properties.segment_length_ratio().
Segment energy flux. This implementation does not average spatially contiguous contrail segments when calculating the mean energy flux for the segment of interest. See contrail_properties.mean_energy_flux_per_m().

This implementation is regression tested against results from [Teoh et al., 2022].

Outputs

NaN values may appear in model output. Specifically, np.nan values are used to indicate:

Flight waypoint or contrail waypoint is not contained with the met domain.
The variable was NOT computed during the model evaluation. For example, at flight waypoints not producing any persistent contrails, “radiative” variables (rsr, olr, rf_sw, rf_lw, rf_net) are not computed. Consequently, the corresponding values in the output of eval() are NaN. One exception to this rule is found on ef (energy forcing) contrail_age predictions. For these two “cumulative” variables, waypoints not producing any persistent contrails are assigned 0 values.

References

See also

CocipFlightParams, wake_vortex, contrail_properties, radiative_forcing, humidity_scaling, Emissions, sac, tau_cirrus

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

Methods

`__init__`(met, rad[, params])
`downselect_met`()	Downselect `met` domain to the max/min bounds of `source`.
`eval`([source])	Run CoCiP simulation on flight.
`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 evolution output from model.
`contrail_dataset`	`xr.Dataset` representation of contrail evolution.
`contrail_list`	List of `GeoVectorDataset` contrail objects - one for each timestep
`rad`	Radiation data formatted as a `MetDataset` at a single pressure level [-1]
`timesteps`	Array of `numpy.datetime64` time steps for contrail evolution
`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`
`optional_met_variables`	Additional met variables used to support outputs
`params`	Instantiated model parameters, in dictionary form
`processed_met_variables`	Minimal set of met variables needed to run the model after pre-processing.
`rad_variables`	Required single-level top of atmosphere radiation variables.
`source`	Last Flight modeled in `eval()`

contrail¶

Contrail evolution output from model.

Set to None when no contrails are formed. Otherwise, this is a pandas.DataFrame describing the evolution of the contrail. Columns include:

waypoint: The index of the waypoint in the original flight creating the contrail. This can be used to join the contrail DataFrame to the source.
formation_time: Time of contrail formation. Agrees with the time column in source.
continuous: Boolean indicating whether the contrail is continuous or not.
persistent: Boolean indicating whether the contrail is persistent or not. A contrail segment is considered continuous if both the current and the next contrail waypoint at the same time step persist.
segment_length: Length of the contrail segment, [\(m\)].
sin_a, cos_a: Sine and cosine of the segment angle.
width, depth: Contrail width and depth, [\(m\)].
sigma_yz: The yz component of the covariance matrix, [\(m^{2}\)]. See contrail_properties.plume_temporal_evolution().
q_sat: Saturation specific humidity over ice, [\(kg \ kg^{-1}\)].
n_ice_per_m: Number of ice particles per distance, [\(m^{-1}\)].
iwc: Ice water content, [\(kg_{ice} kg_{air}^{-1}\)].
tau_contrail: Optical depth of the contrail. See contrail_properties.contrail_optical_depth().
rf_sw, rf_lw, rf_net: Shortwave, longwave, and net instantaneous radiative forcing, [\(W \ m^{-2}\)] at the contrail waypoint.
ef: Energy forcing, [\(J\)] at the contrail waypoint. See contrail_properties.energy_forcing().

contrail_dataset¶: xr.Dataset representation of contrail evolution.

contrail_list¶: List of GeoVectorDataset contrail objects - one for each timestep

default_params¶: alias of CocipFlightParams

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.

eval(source=None, **params)¶

Run CoCiP simulation on flight.

Simulates the formation and evolution of contrails from a Flight using the contrail cirrus prediction model (CoCiP) from Schumann (2012) [Schumann, 2012].

Changed in version 0.25.11: Previously, any waypoint not surviving the wake vortex downwash phase of CoCiP was assigned a nan-value in the ef array within the model output. This is no longer the case. Instead, energy forcing is set to 0.0 for all waypoints which fail to produce persistent contrails. In particular, nan values in the ef array are only used to indicate an out-of-met-domain waypoint. The same convention is now used for output variables contrail_age and cocip as well.

Parameters:

source (Flight | Sequence[Flight] | None) – Input Flight(s) to model.
**params (Any) – Overwrite model parameters before eval.

Returns:

Flight | list[Flight] | NoReturn – Flight(s) with updated Contrail data. The model parameter “verbose_outputs” determines the variables on the return flight object.

References

[Schumann, 2012]

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:

source.data[key]. Returns np.ndarray | xr.DataArray.
source.attrs[key]
params[key]
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.