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 evaluationsource
parameters.- Parameters:
met, rad (
MetDataset
) – CoCiP-specific met data to interpolate againstparams (
dict[str
,Any]
, optional) – OverrideCocipGridParams
defaults. Most notably, the model is highly dependent on the parameterdt_integration
. Memory usage is also affected by parametersmet_slice_dt
andtarget_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 ofrad
by half a forecast step. A warning will be produced duringeval()
if the time coverage ofrad
(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 ofrad
.
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 ofsource
.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
istype_
.set_source
([source])Attach original or copy of input
source
tosource
.set_source_met
([optional, variable])Ensure or interpolate each required
met_variables
onsource
.transfer_met_source_attrs
([source])Transfer met source metadata from
met
tosource
.update_params
([params])Update model parameters on
params
.Attributes
Artifacts attached when parameter
verbose_outputs_evolution
is True These allow for some additional information and parity with the approach taken byCocip
.hash
Generate a unique hash for model instance.
interp_kwargs
Shortcut to create interpolation arguments from
params
.met
Met data is not optional
Require meteorology is not None on __init__()
Required meteorology pressure level variables.
params
Instantiated model parameters, in dictionary form
Set of required parameters if processing already complete on
met
input.source
Last evaluated input source
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 byCocip
.
- 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 passedmet
andrad
data, this parameter should avoid the extreme values of themet
and rad levels. Ifmet
is already defined, a good choice forlevel
ismet.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 oflon_step
andlat_step
are used to definelongitude
andlatitude
. 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 parameterlongitude
(respectivelatitude
) not specified.
- Returns:
MetDataset
– MetDataset that can be used assource
input toCocipGrid.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 holdscontrail_list
andcontrail
attributes for viewing intermediate artifacts. Ifsource
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 aGeoVectorDataset
. In order to evaluate CoCiP predictions over a flight trajectory, it is best to use theCocip
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
) – InputGeoVectorDataset
orMetDataset
. If None, aNotImplementedError
is raised. If any subclass ofGeoVectorDataset
is passed (e.g.,Flight
), the additional structure is forgotten and the model is evaluated as if it were aGeoVectorDataset
. Additional variables may be passed assource
data or attrs. These include:aircraft_type
: This overrides any value inparams
. Must be included in the source attrs (not data).fuel_flow
,engine_efficiency
,true_airspeed
,wingspan
,aircraft_mass
: These override any value inparams
.azimuth
: This overrides any value inparams
.segment_length
: This overrides any value inparams
.
**params (
Any
) – Overwrite model parameters before eval
- Returns:
GeoVectorDataset | MetDataset
– CoCiP predictions for each point insource
. Output data contains variablescontrail_age
andef_per_m
. Additional variables specified by the modelparams
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
toGeoVectorDataset
.Split the
source
into chunks of sizeparams["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 atuple[MetVariable]
. If element is atuple[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¶