pycontrails.models.cocipgrid.CocipGridParams

class pycontrails.models.cocipgrid.CocipGridParams(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')), process_emissions=True, dt_integration=np.timedelta64(30, 'm'), dz_m=200.0, effective_vertical_resolution=2000.0, smooth_true_airspeed=True, smooth_true_airspeed_window_length=7, smooth_true_airspeed_polyorder=1, humidity_scaling=None, preprocess_lowmem=False, compute_tau_cirrus_in_model_init='auto', filter_sac=True, filter_initially_persistent=True, persistent_buffer=None, verbose_outputs=False, compute_atr20=False, global_rf_to_atr20_factor=0.0151, initial_wake_vortex_depth=0.5, sedimentation_impact_factor=0.5, default_nvpm_ei_n=1000000000000000.0, wind_shear_enhancement_exponent=0.5, nvpm_ei_n_enhancement_factor=1.0, min_ice_particle_number_nvpm_ei_n=10000000000000.0, max_depth=1500.0, unterstrasser_ice_survival_fraction=False, radiative_heating_effects=False, contrail_contrail_overlapping=False, dz_overlap_m=500.0, radius_threshold_um=<factory>, habits=<factory>, habit_distributions=<factory>, rf_sw_enhancement_factor=1.0, rf_lw_enhancement_factor=1.0, min_altitude_m=6000.0, max_altitude_m=13000.0, max_seg_length_m=40000.0, max_age=np.timedelta64(20, 'h'), min_tau=1e-06, max_tau=10000000000.0, min_n_ice_per_m3=1000.0, max_n_ice_per_m3=1e+20, target_split_size=100000, target_split_size_pre_SAC_boost=3.0, show_progress=True, segment_length=1000.0, fuel=<factory>, aircraft_type='B737', engine_uid=None, azimuth=0.0, dsn_dz_factor=0.0, wingspan=None, aircraft_mass=None, true_airspeed=None, engine_efficiency=None, fuel_flow=None, aircraft_performance=None, verbose_outputs_formation=False, verbose_outputs_evolution=False)

Bases: CocipParams

Default parameters for CocipGrid.

__init__(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')), process_emissions=True, dt_integration=np.timedelta64(30, 'm'), dz_m=200.0, effective_vertical_resolution=2000.0, smooth_true_airspeed=True, smooth_true_airspeed_window_length=7, smooth_true_airspeed_polyorder=1, humidity_scaling=None, preprocess_lowmem=False, compute_tau_cirrus_in_model_init='auto', filter_sac=True, filter_initially_persistent=True, persistent_buffer=None, verbose_outputs=False, compute_atr20=False, global_rf_to_atr20_factor=0.0151, initial_wake_vortex_depth=0.5, sedimentation_impact_factor=0.5, default_nvpm_ei_n=1000000000000000.0, wind_shear_enhancement_exponent=0.5, nvpm_ei_n_enhancement_factor=1.0, min_ice_particle_number_nvpm_ei_n=10000000000000.0, max_depth=1500.0, unterstrasser_ice_survival_fraction=False, radiative_heating_effects=False, contrail_contrail_overlapping=False, dz_overlap_m=500.0, radius_threshold_um=<factory>, habits=<factory>, habit_distributions=<factory>, rf_sw_enhancement_factor=1.0, rf_lw_enhancement_factor=1.0, min_altitude_m=6000.0, max_altitude_m=13000.0, max_seg_length_m=40000.0, max_age=np.timedelta64(20, 'h'), min_tau=1e-06, max_tau=10000000000.0, min_n_ice_per_m3=1000.0, max_n_ice_per_m3=1e+20, target_split_size=100000, target_split_size_pre_SAC_boost=3.0, show_progress=True, segment_length=1000.0, fuel=<factory>, aircraft_type='B737', engine_uid=None, azimuth=0.0, dsn_dz_factor=0.0, wingspan=None, aircraft_mass=None, true_airspeed=None, engine_efficiency=None, fuel_flow=None, aircraft_performance=None, verbose_outputs_formation=False, verbose_outputs_evolution=False)

Methods

__init__([copy_source, ...])

as_dict()

Convert object to dictionary.

Attributes

aircraft_mass

Nominal aircraft mass, [\(kg\)].

aircraft_performance

Aircraft performance model.

aircraft_type

ICAO code designating simulated aircraft type.

azimuth

Navigation bearing [\(\deg\)] measured in clockwise direction from true north, by default 0.0.

compute_atr20

Add additional metric of ATR20 and global yearly mean RF to model output.

compute_tau_cirrus_in_model_init

Compute "tau_cirrus" variable in pressure-level met data during model initialization.

contrail_contrail_overlapping

Experimental.

copy_source

Copy input source data on eval

default_nvpm_ei_n

Default nvpm_ei_n value if no data provided and emissions calculations fails.

downselect_met

Downselect input MetDataset` to region around source.

dsn_dz_factor

Experimental parameter used to approximate dsn_dz from ds_dz via dsn_dz = ds_dz * dsn_dz_factor.

dt_integration

Apply Euler's method with a fixed step size of dt_integration.

dz_m

Difference in altitude between top and bottom layer for stratification calculations, [\(m\)].

dz_overlap_m

Experimental.

effective_vertical_resolution

Vertical resolution (m) associated to met data.

engine_efficiency

Nominal engine efficiency, [\(0 - 1\)].

engine_uid

Engine unique identification number for the ICAO Aircraft Emissions Databank (EDB) If None, an assumed engine_uid is used in Emissions.

filter_initially_persistent

Filter out waypoints if they don't satisfy the initial persistent criteria Passing in a non-default value is unusual, but is included to allow for false negative calibration and model uncertainty studies.

filter_sac

Filter out waypoints if the don't satisfy the SAC criteria Note that the SAC algorithm will still be run to calculate T_critical_sac for use estimating initial ice particle number.

fuel_flow

Nominal fuel flow, [\(kg \ s^{-1}\)].

global_rf_to_atr20_factor

Constant factor used to convert global- and year-mean RF, [\(W m^{-2}\)], to ATR20, [\(K\)], given by [Yin et al., 2023].

humidity_scaling

Humidity scaling

initial_wake_vortex_depth

Initial wake vortex depth scaling factor.

interpolation_bounds_error

If True, points lying outside interpolation will raise an error

interpolation_fill_value

Used for outside interpolation value if interpolation_bounds_error is False

interpolation_localize

Experimental.

interpolation_method

Interpolation method.

interpolation_q_method

Experimental.

interpolation_use_indices

Experimental.

max_age

Max age of contrail evolution.

max_altitude_m

Maximum altitude domain in simulation, [\(m\)] If set to None, this check is disabled.

max_depth

Upper bound for contrail plume depth, constraining it to realistic values.

max_n_ice_per_m3

Maximum contrail ice particle number per volume of air to prevent unrealistic values.

max_seg_length_m

Maximum contrail segment length in simulation to prevent unrealistic values, [\(m\)].

max_tau

Maximum contrail optical depth to prevent unrealistic values.

met_latitude_buffer

Met latitude buffer [WGS84] for Cocip evolution.

met_level_buffer

Met level buffer [\(hPa\)] for Cocip initialization and evolution.

met_longitude_buffer

Met longitude [WGS84] buffer for Cocip evolution.

met_time_buffer

Met time buffer for input to Flight.downselect_met() Only applies when downselect_met is True.

min_altitude_m

Minimum altitude domain in simulation, [\(m\)] If set to None, this check is disabled.

min_ice_particle_number_nvpm_ei_n

Lower bound for nvpm_ei_n to account for ambient aerosol particles for newer engines, [\(kg^{-1}\)]

min_n_ice_per_m3

Minimum contrail ice particle number per volume of air.

min_tau

Minimum contrail optical depth.

nvpm_ei_n_enhancement_factor

Multiply flight black carbon number by enhancement factor.

persistent_buffer

Continue evolving contrail waypoints persistent_buffer beyond end of contrail life.

preprocess_lowmem

Experimental.

process_emissions

Determines whether Cocip.process_emissions() runs on model Cocip.eval() Set to False when input Flight includes emissions data.

radiative_heating_effects

Experimental.

rf_lw_enhancement_factor

Scale longwave radiative forcing.

rf_sw_enhancement_factor

Scale shortwave radiative forcing.

sedimentation_impact_factor

Sedimentation impact factor.

segment_length

Nominal segment length to place at each grid point [\(m\)].

show_progress

Display tqdm progress bar showing batch evaluation progress.

smooth_true_airspeed

Smoothing parameters for true airspeed.

smooth_true_airspeed_polyorder

smooth_true_airspeed_window_length

target_split_size

Approximate size of a typical numpy.ndarray used with in CoCiP calculations.

target_split_size_pre_SAC_boost

Additional boost to target split size before SAC is computed.

true_airspeed

Cruising true airspeed, [\(m \ s^{-1}\)].

unterstrasser_ice_survival_fraction

Experimental.

verbose_outputs

Add additional values to the flight and contrail that are not explicitly necessary for calculation.

verbose_outputs_evolution

Attach contrail evolution data to CocipGrid.contrail_list.

verbose_outputs_formation

Attach additional formation specific data to the output.

verify_met

Call _verify_met() on model instantiation.

wind_shear_enhancement_exponent

Parameter denoted by \(n\) in eq.

wingspan

Aircraft wingspan, [\(m\)].

fuel

Fuel type

radius_threshold_um

Radius threshold for regime bins, [\(\mu m\)] This is the row index label for habit_distributions.

habits

Particle habit (shape) types.

habit_distributions

Mix of ice particle habits in each radius regime.

aircraft_mass = None

Nominal aircraft mass, [\(kg\)]. If included in CocipGrid.source, this parameter is unused. Otherwise, if this parameter is None, the aircraft_performance model is used to estimate the aircraft mass.

aircraft_performance = None

Aircraft performance model. Required unless source or params provide all of the following variables:

  • wingspan

  • true_airspeed (or mach_number)

  • fuel_flow

  • engine_efficiency

  • aircraft_mass

If None and CocipGrid.source or CocipGridParams do not provide the above variables, a ValueError is raised. See PSGrid for an open-source implementation of a AircraftPerformanceGrid model.

aircraft_type = 'B737'

ICAO code designating simulated aircraft type. Needed for the aircraft_performance and Emissions 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.

azimuth = 0.0

Navigation bearing [\(\deg\)] measured in clockwise direction from true north, by default 0.0.

Added in version 0.32.2.

EXPERIMENTAL: If None, run CoCiP in “segment-free” mode. This mode does not include any terms involving segments (wind shear, segment_length, any derived terms), unless dsn_dz_factor is non-zero.

compute_atr20 = False

Add additional metric of ATR20 and global yearly mean RF to model output. These are not standard CoCiP outputs but based on the derivation used in the first supplement to [Yin et al., 2023]. ATR20 is defined as the average temperature response over a 20 year horizon.

compute_tau_cirrus_in_model_init = 'auto'

Compute "tau_cirrus" variable in pressure-level met data during model initialization. Must be one of "auto", True, or False. If set to "auto", "tau_cirrus" will be computed during model initialization iff the met data is dask-backed. Otherwise, it will be computed during model evaluation after the met data is downselected.

contrail_contrail_overlapping = False

Experimental. Radiative effects due to contrail-contrail overlapping Account for change in local contrail shortwave and longwave radiative forcing due to contrail-contrail overlapping.

Added in version 0.45.

copy_source = True

Copy input source data on eval

default_nvpm_ei_n = 1000000000000000.0

Default nvpm_ei_n value if no data provided and emissions calculations fails.

downselect_met = True

Downselect input MetDataset` to region around source.

dsn_dz_factor = 0.0

Experimental parameter used to approximate dsn_dz from ds_dz via dsn_dz = ds_dz * dsn_dz_factor. A value of 0.0 disables any normal wind shear effects. An initial unpublished experiment suggests that dsn_dz_factor = 0.665 adequately approximates the mean EF predictions of CocipGrid over all azimuths.

Added in version 0.32.2.

dt_integration = np.timedelta64(30,'m')

Apply Euler’s method with a fixed step size of dt_integration. Advected waypoints are interpolated against met data once each dt_integration.

dz_m = 200.0

Difference in altitude between top and bottom layer for stratification calculations, [\(m\)]. Used to approximate derivative of “lagrangian_tendency_of_air_pressure” layer.

dz_overlap_m = 500.0

Experimental. Contrail-contrail overlapping altitude interval If contrail_contrail_overlapping is set to True, contrails will be grouped into altitude intervals, and all contrails within each altitude interval are treated as one contrail layer where they do not overlap.

effective_vertical_resolution = 2000.0

Vertical resolution (m) associated to met data. Constant below applies to ECMWF data.

engine_efficiency = None

Nominal engine efficiency, [\(0 - 1\)]. If included in CocipGrid.source, this parameter is unused. Otherwise, if this parameter is None, the aircraft_performance model is used to estimate the engine efficiency.

engine_uid = None

Engine unique identification number for the ICAO Aircraft Emissions Databank (EDB) If None, an assumed engine_uid is used in Emissions.

filter_initially_persistent = True

Filter out waypoints if they don’t satisfy the initial persistent criteria Passing in a non-default value is unusual, but is included to allow for false negative calibration and model uncertainty studies.

filter_sac = True

Filter out waypoints if the don’t satisfy the SAC criteria Note that the SAC algorithm will still be run to calculate T_critical_sac for use estimating initial ice particle number. Passing in a non-default value is unusual, but is included to allow for false negative calibration and model uncertainty studies.

fuel

Fuel type

fuel_flow = None

Nominal fuel flow, [\(kg \ s^{-1}\)]. If included in CocipGrid.source, this parameter is unused. Otherwise, if this parameter is None, the aircraft_performance model is used to estimate the fuel flow.

global_rf_to_atr20_factor = 0.0151

Constant factor used to convert global- and year-mean RF, [\(W m^{-2}\)], to ATR20, [\(K\)], given by [Yin et al., 2023].

habit_distributions

Mix of ice particle habits in each radius regime. Rows indexes are radius_threshold_um elements. Columns indexes are habits particle habit type. See Table 2 from [Schumann et al., 2011].

habits

Particle habit (shape) types. This is the column index label for habit_distributions. See Table 2 in [Schumann et al., 2011].

humidity_scaling = None

Humidity scaling

initial_wake_vortex_depth = 0.5

Initial wake vortex depth scaling factor. This factor scales max contrail downward displacement after the wake vortex phase to set the initial contrail depth. Denoted \(C_{D0}\) in eq (14) in [Schumann, 2012].

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.

max_age = np.timedelta64(20,'h')

Max age of contrail evolution.

max_altitude_m = 13000.0

Maximum altitude domain in simulation, [\(m\)] If set to None, this check is disabled.

max_depth = 1500.0

Upper bound for contrail plume depth, constraining it to realistic values. CoCiP only uses the ambient conditions at the mid-point of the Gaussian plume, and the edges could be in subsaturated conditions and sublimate. Important when radiative_heating_effects is enabled.

max_n_ice_per_m3 = 1e+20

Maximum contrail ice particle number per volume of air to prevent unrealistic values.

max_seg_length_m = 40000.0

Maximum contrail segment length in simulation to prevent unrealistic values, [\(m\)].

max_tau = 10000000000.0

Maximum contrail optical depth to prevent unrealistic values.

met_latitude_buffer = (10.0, 10.0)

Met latitude buffer [WGS84] for Cocip evolution.

met_level_buffer = (40.0, 40.0)

Met level buffer [\(hPa\)] for Cocip initialization and evolution.

met_longitude_buffer = (10.0, 10.0)

Met longitude [WGS84] buffer for Cocip evolution.

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.

min_altitude_m = 6000.0

Minimum altitude domain in simulation, [\(m\)] If set to None, this check is disabled.

min_ice_particle_number_nvpm_ei_n = 10000000000000.0

Lower bound for nvpm_ei_n to account for ambient aerosol particles for newer engines, [\(kg^{-1}\)]

min_n_ice_per_m3 = 1000.0

Minimum contrail ice particle number per volume of air.

min_tau = 1e-06

Minimum contrail optical depth.

nvpm_ei_n_enhancement_factor = 1.0

Multiply flight black carbon number by enhancement factor. A value of 1.0 provides no scaling. Primarily used to support uncertainty estimation.

persistent_buffer = None

Continue evolving contrail waypoints persistent_buffer beyond end of contrail life. Passing in a non-default value is unusual, but is included to allow for false negative calibration and model uncertainty studies.

preprocess_lowmem = False

Experimental. If True, attempt to reduce memory consumption during aircraft performance and initial contrail formation/persistent calculations by calling MetDataArray.interpolate() with lowmem=True.

IMPORTANT:

  • Memory optimizations used when proprocess_lowmem=True are designed for meteorology backed by dask arrays with a chunk size of 1 along the time dimension. This option may degrade performance if dask if not used or if chunks contain more than a single time step.

  • The impact on runtime of setting preprocess_lowmem=True depends on how meteorology data is chunked. Runtime is likely to increase if meteorology data is chunked in time only, but may decrease if meteorology data is also chunked in longitude, latitude, and level.

  • Changes to data access patterns with preprocess_lowmem=True alter locations where interpolation is in- vs out-of-bounds. As a consequence, Cocip output with preprocess_lowmem=True is only guaranteed to match output with preprocess_lowmem=False when run with interpolation_bounds_error=True to ensure no out-of-bounds interpolation occurs.

process_emissions = True

Determines whether Cocip.process_emissions() runs on model Cocip.eval() Set to False when input Flight includes emissions data.

radiative_heating_effects = False

Experimental. Radiative heating effects on contrail cirrus properties. Terrestrial and solar radiances warm the contrail ice particles and cause convective turbulence. This effect is expected to enhance vertical mixing and reduce the lifetime of contrail cirrus. This parameter is experimental, and the CoCiP implementation of this parameter may change.

Added in version 0.28.9.

radius_threshold_um

Radius threshold for regime bins, [\(\mu m\)] This is the row index label for habit_distributions. See Table 2 in [Schumann et al., 2011].

rf_lw_enhancement_factor = 1.0

Scale longwave radiative forcing. Primarily used to support uncertainty estimation.

rf_sw_enhancement_factor = 1.0

Scale shortwave radiative forcing. Primarily used to support uncertainty estimation.

sedimentation_impact_factor = 0.5

Sedimentation impact factor. Denoted by \(f_{T}\) in eq. (35) of [Schumann, 2012]. Schumann describes this as “an important adjustable parameter”, and sets it to 0.1 in the original publication. In [Schumann and Graf, 2013], a value of 0.5 is referenced after comparing CoCiP predictions to observations.

segment_length = 1000.0

Nominal segment length to place at each grid point [\(m\)]. Round-off error can be problematic with a small nominal segment length and a large dt_integration parameter. On the other hand, too large of a nominal segment length diminishes the “locality” of the grid point.

Added in version 0.32.2.

EXPERIMENTAL: If None, run CoCiP in “segment-free” mode. This mode does not include any terms involving segments (wind shear, segment length, any derived terms). See azimuth and dsn_dz_factor for more details.

show_progress = True

Display tqdm progress bar showing batch evaluation progress.

smooth_true_airspeed = True

Smoothing parameters for true airspeed. Only used for Flight models. Passed directly to scipy.signal.savgol_filter(). See pycontrails.Flight.segment_true_airspeed() for details.

smooth_true_airspeed_polyorder = 1
smooth_true_airspeed_window_length = 7
target_split_size = 100000

Approximate size of a typical numpy.ndarray used with in CoCiP calculations. The 4-dimensional array defining the waypoint is raveled and split into batches of this size. A smaller number for this parameter will reduce memory footprint at the expense of a longer compute time.

target_split_size_pre_SAC_boost = 3.0

Additional boost to target split size before SAC is computed. For typical meshes, only 10% of waypoints will survive SAC and initial downwash filtering. Accordingly, this parameter magnifies mesh split size before SAC is computed. See target_split_size.

true_airspeed = None

Cruising true airspeed, [\(m \ s^{-1}\)]. If included in CocipGrid.source, this parameter is unused. Otherwise, if this parameter is None, the aircraft_performance model is used to estimate the true airspeed.

unterstrasser_ice_survival_fraction = False

Experimental. Improved ice crystal number survival fraction in the wake vortex phase. Implement [Unterstrasser, 2016], who developed a parametric model that estimates the survival fraction of the contrail ice crystal number after the wake vortex phase based on the results from large eddy simulations. This replicates Fig. 4 of [Kärcher, 2018].

Added in version 0.50.1.

verbose_outputs = False

Add additional values to the flight and contrail that are not explicitly necessary for calculation. See also CocipGridParams.verbose_outputs_formation and CocipGridParams.verbose_outputs_evolution.

verbose_outputs_evolution = False

Attach contrail evolution data to CocipGrid.contrail_list. Requires substantial memory overhead.

verbose_outputs_formation = False

Attach additional formation specific data to the output. If True, attach all possible formation data. See pycontrails.models.cocipgrid.cocip_grid for a list of supported formation data.

verify_met = True

Call _verify_met() on model instantiation.

wind_shear_enhancement_exponent = 0.5

Parameter denoted by \(n\) in eq. (39) of [Schumann, 2012].

wingspan = None

Aircraft wingspan, [\(m\)]. If included in CocipGrid.source, this parameter is unused. Otherwise, if this parameter is None, the aircraft_performance model is used to estimate the wingspan.