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
Attributes
Nominal aircraft mass, [\(kg\)].
Aircraft performance model.
ICAO code designating simulated aircraft type.
Navigation bearing [\(\deg\)] measured in clockwise direction from true north, by default 0.0.
Add additional metric of ATR20 and global yearly mean RF to model output.
Compute
"tau_cirrus"
variable in pressure-level met data during model initialization.Experimental.
Copy input
source
data on evalDefault
nvpm_ei_n
value if no data provided and emissions calculations fails.Downselect input
MetDataset`
to region aroundsource
.Experimental parameter used to approximate
dsn_dz
fromds_dz
viadsn_dz = ds_dz * dsn_dz_factor
.Apply Euler's method with a fixed step size of
dt_integration
.Difference in altitude between top and bottom layer for stratification calculations, [\(m\)].
Experimental.
Vertical resolution (m) associated to met data.
Nominal engine efficiency, [\(0 - 1\)].
Engine unique identification number for the ICAO Aircraft Emissions Databank (EDB) If None, an assumed engine_uid is used in
Emissions
.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 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.Nominal fuel flow, [\(kg \ s^{-1}\)].
Constant factor used to convert global- and year-mean RF, [\(W m^{-2}\)], to ATR20, [\(K\)], given by [Yin et al., 2023].
Humidity scaling
Initial wake vortex depth scaling factor.
If True, points lying outside interpolation will raise an error
Used for outside interpolation value if
interpolation_bounds_error
is FalseExperimental.
Interpolation method.
Experimental.
Experimental.
Max age of contrail evolution.
Maximum altitude domain in simulation, [\(m\)] If set to
None
, this check is disabled.Upper bound for contrail plume depth, constraining it to realistic values.
Maximum contrail ice particle number per volume of air to prevent unrealistic values.
Maximum contrail segment length in simulation to prevent unrealistic values, [\(m\)].
Maximum contrail optical depth to prevent unrealistic values.
Met latitude buffer [WGS84] for Cocip evolution.
Met level buffer [\(hPa\)] for Cocip initialization and evolution.
Met longitude [WGS84] buffer for Cocip evolution.
Met time buffer for input to
Flight.downselect_met()
Only applies whendownselect_met
is True.Minimum altitude domain in simulation, [\(m\)] If set to
None
, this check is disabled.Lower bound for
nvpm_ei_n
to account for ambient aerosol particles for newer engines, [\(kg^{-1}\)]Minimum contrail ice particle number per volume of air.
Minimum contrail optical depth.
Multiply flight black carbon number by enhancement factor.
Continue evolving contrail waypoints
persistent_buffer
beyond end of contrail life.Experimental.
Determines whether
Cocip.process_emissions()
runs on modelCocip.eval()
Set toFalse
when input Flight includes emissions data.Experimental.
Scale longwave radiative forcing.
Scale shortwave radiative forcing.
Sedimentation impact factor.
Nominal segment length to place at each grid point [\(m\)].
Display
tqdm
progress bar showing batch evaluation progress.Smoothing parameters for true airspeed.
Approximate size of a typical
numpy.ndarray
used with in CoCiP calculations.Additional boost to target split size before SAC is computed.
Cruising true airspeed, [\(m \ s^{-1}\)].
Experimental.
Add additional values to the flight and contrail that are not explicitly necessary for calculation.
Attach contrail evolution data to
CocipGrid.contrail_list
.Attach additional formation specific data to the output.
Call
_verify_met()
on model instantiation.Parameter denoted by \(n\) in eq.
Aircraft wingspan, [\(m\)].
Fuel type
Radius threshold for regime bins, [\(\mu m\)] This is the row index label for
habit_distributions
.Particle habit (shape) types.
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, theaircraft_performance
model is used to estimate the aircraft mass.
- aircraft_performance = None¶
Aircraft performance model. Required unless
source
orparams
provide all of the following variables:wingspan
true_airspeed (or mach_number)
fuel_flow
engine_efficiency
aircraft_mass
If None and
CocipGrid.source
orCocipGridParams
do not provide the above variables, a ValueError is raised. SeePSGrid
for an open-source implementation of aAircraftPerformanceGrid
model.
- aircraft_type = 'B737'¶
ICAO code designating simulated aircraft type. Needed for the
aircraft_performance
andEmissions
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
, orFalse
. 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 aroundsource
.
- dsn_dz_factor = 0.0¶
Experimental parameter used to approximate
dsn_dz
fromds_dz
viadsn_dz = ds_dz * dsn_dz_factor
. A value of 0.0 disables any normal wind shear effects. An initial unpublished experiment suggests thatdsn_dz_factor = 0.665
adequately approximates the mean EF predictions ofCocipGrid
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 eachdt_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, theaircraft_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, theaircraft_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 arehabits
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"
. IfNone
, 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 tointerpolate_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 whendownselect_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 callingMetDataArray.interpolate()
withlowmem=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 withpreprocess_lowmem=True
is only guaranteed to match output withpreprocess_lowmem=False
when run withinterpolation_bounds_error=True
to ensure no out-of-bounds interpolation occurs.
- process_emissions = True¶
Determines whether
Cocip.process_emissions()
runs on modelCocip.eval()
Set toFalse
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
anddsn_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()
. Seepycontrails.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, theaircraft_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
andCocipGridParams.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, theaircraft_performance
model is used to estimate the wingspan.