pycontrails.models.apcemm.APCEMM¶

class pycontrails.models.apcemm.APCEMM(met, apcemm_path, apcemm_root=None, apcemm_input_params=None, cachestore=None, params=None, **params_kwargs)¶

Bases: Model

Run APCEMM as a pycontrails Model.

This class acts as an adapter between the pycontrails Model interface (shared with other contrail models) and APCEMM’s native interface.

APCEMM was developed at the MIT Laboratory for Aviation and the Environment and is described in [Fritz et al., 2020].

Parameters:

met (MetDataset) – Pressure level dataset containing met_variables variables. See Notes for variable names by data source.
apcemm_path (pathlib.Path | str) – Path to APCEMM executable. See Notes for information about acquiring and compiling APCEMM.
apcemm_root (pathlib.Path | str, optional) – Path to APCEMM root directory, used to set input_background_conditions and input_engine_emissions based on the structure of the APCEMM GitHub repository. If not provided, pycontrails will use the default paths defined in APCEMMInput.
apcemm_input_params (APCEMMInput, optional) – Value for APCEMM input parameters defined in APCEMMInput. If provided, values for input_background_condition or input_engine_emissions will override values set based on apcemm_root. Attempting to provide values for input parameters that are determined automatically by this interface will result in an error. See Notes for detailed information about YAML file generation.
cachestore (CacheStore, optional) – CacheStore used to store APCEMM run directories. If not provided, uses a DiskCacheStore. See Notes for detailed information about the file structure for APCEMM simulations.
params (dict[str,Any], optional) – Override APCEMM model parameters with dictionary. See APCEMMParams for model parameters.
**params_kwargs (Any) – Override Cocip model parameters with keyword arguments. See APCEMMParams for model parameters.

Notes

Meteorology

APCEMM requires temperature, humidity, gepotential height, and winds. Geopotential height is required because APCEMM expects meteorological fields on height rather than pressure surfaces. See met_variables for the list of required variables.

Variable keys for pressure level data¶
Parameter	ECMWF	GFS
Air Temperature	`air_temperature`	`air_temperature`
Specific Humidity	`specific_humidity`	`specific_humidity`
Geopotential/Geopotential Height	`geopotential`	`geopotential_height`
Eastward wind	`eastward_wind`	`eastward_wind`
Northward wind	`northward_wind`	`northward_wind`
Vertical velocity	`lagrangian_tendency_of_air_pressure`	`lagrangian_tendency_of_air_pressure`

Acquiring and compiling APCEMM

Users are responsible for acquiring and compiling APCEMM. The APCEMM source code is available through GitHub, and instructions for compiling APCEMM are available in the repository.

Note that APCEMM does not provide versioned releases, and future updates may break this interface. To guarantee compatibility between this interface and APCEMM, users should use commit 9d8e1ee from the APCEMM repository.

Configuring APCEMM YAML files

APCEMMInput provides low-level control over the contents of YAML files used as APCEMM input. YAML file contents can be controlled by passing custom parameters in a dictionary through the apcemm_input_params parameter. Note, however, that APCEMM sets a number of APCEMM input parameters automatically, and attempting to override any automatically-determined parameters using apcemm_input_params will result in an error. A list of automatically-determined parameters is available in dynamic_yaml_params.

Simulation initialization, execution, and postprocessing

This interface initializes, runs, and postprocesses APCEMM simulations in four stages:

A DryAdvection model is used to generate trajectories for contrails initialized at each flight waypoint. This is a necessary preprocessing step because APCEMM is a Lagrangian model and does not explicitly track changes in plume location over time. This step also provides time-dependent azimuths that define the orientation of advected contrails, which is required to compute contrail-normal wind shear from horizontal winds. Results from the trajectory calculation are stored in trajectories.
Model parameters and results from the trajectory calculation are used to generate YAML files with APCEMM input parameters and netCDF files with meteorology data used by APCEMM simulations. A separate pair of files is generated for each waypoint processed by APCEMM. Files are saved as apcemm_waypoint_/input.yaml and apcemm_waypoint_/input.nc in the model cachestore, where  is replaced by the index of each simulated flight waypoint.
A separate APCEMM simulation is run in each run directory inside the model cachestore. Simulations are independent and can be run in parallel (controlled by the n_jobs parameter in APCEMMParams). Standard output and error streams from each simulation are saved in apcemm_waypoint_/stdout.log and apcemm_waypoint_/stderr.log, and APCEMM output is saved in a subdirectory specified by the output_directory model parameter (“out” by default).
APCEMM simulation output is postprocessed. After postprocessing:

A status column is attached to the Flight returned by eval(). This column contains "NoSimulation" for waypoints where no simulation was run and the contents of the APCEMM status_case0 output file for other waypoints.
A pd.DataFrame is created and stored in vortex. This dataframe contains time series output from the APCEMM “early plume model” of the aircraft exhaust plume and downwash vortex, read from Micro_000000.out output files saved by APCEMM.
If APCEMM simulated at least one persistent contrail, A pd.DataFrame is created and stored in contrail. This dataframe contains paths to netCDF files, saved at prescribed time intervals during the APCEMM simulation, and can be used to open APCEMM output (e.g., using xr.open_dataset()) for further analysis.

Numerics

APCEMM simulations are initialized at flight waypoints and represent the evolution of the cross-section of contrails formed at each waypoint. APCEMM does not explicitly model the length of contrail segments and does not include any representation of deformation by divergent flow. APCEMM output represents properties of cross-sections of contrails formed at flight waypoints, not properties of contrail segments that form between flight waypoints. Unlike Cocip, output produced by this interface does not include trailing NaN values.

Known limitations

Engine core exit temperature and bypass area are not provided as output by pycontrails aircraft performance models and are currently set to static values in APCEMM input files. These parameters will be computed dynamically in a future release.
APCEMM does not compute contrail radiative forcing internally. Radiative forcing must be computed offline by the user. Tools for radiative forcing calculations may be included in a future version of the interface.
APCEMM currently produces different results in simulations that do not read vertical velocity data from netCDF input files and in simulations that read vertical velocities that are set to 0 everywhere (see https://github.com/MIT-LAE/APCEMM/issues/17). Reading of vertical velocity data from netCDF input files will be disabled in this interface until this issue is resolved.

References

[Fritz et al., 2020]

__init__(met, apcemm_path, apcemm_root=None, apcemm_input_params=None, cachestore=None, params=None, **params_kwargs)¶

Methods

`__init__`(met, apcemm_path[, apcemm_root, ...])
`apcemm_file`(waypoint[, name])	Get path to file from an APCEMM simulation initialized at a specific waypoint.
`attach_apcemm_initial_conditions`()	Compute fields required for APCEMM initial conditions and attach to `source`.
`compute_lagrangian_trajectories`()	Calculate Lagrangian trajectories using a `DryAdvection` model.
`downselect_met`()	Downselect `met` domain to the max/min bounds of `source`.
`eval`([source])	Set up and run APCEMM simulations initialized at flight waypoints.
`generate_apcemm_input`(waypoint)	Generate APCEMM yaml and netCDF input files for a single waypoint.
`get_source_param`(key[, default, set_attr])	Get source data with default set by parameter key.
`process_apcemm_output`()	Process APCEMM output.
`require_met`()	Ensure that `met` is a MetDataset.
`require_source_type`(type_)	Ensure that `source` is `type_`.
`run_apcemm`(waypoints)	Run APCEMM over multiple waypoints.
`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

`apcemm_path`	Path to APCEMM executable
`apcemm_input_params`	Overridden APCEMM input parameters
`cachestore`	CacheStore for APCEMM run directories
`trajectories`	Output from trajectory calculation
`vortex`	Time series output from the APCEMM early plume model
`contrail`	Paths to APCEMM netCDF output at prescribed time intervals
`dynamic_yaml_params`	Set of `APCEMMInput` attributes set dynamically by this model.
`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
`source`	Last flight processed in `eval()`
`processed_met_variables`	Set of required parameters if processing already complete on `met` input.
`optional_met_variables`	Optional meteorology variables

apcemm_file(waypoint, name=None)¶

Get path to file from an APCEMM simulation initialized at a specific waypoint.

Parameters:

waypoint (int) – Segment index
name (str, optional) – If provided, the path to the file relative to the APCEMM simulation root directory.

Returns:

str – Path to a file in the APCEMM simulation root directory, if name is provided, or the path to the APCEMM simulation root directory otherwise.

apcemm_input_params¶: Overridden APCEMM input parameters

apcemm_path¶: Path to APCEMM executable

attach_apcemm_initial_conditions()¶

Compute fields required for APCEMM initial conditions and attach to source.

This modifies source by attaching quantities derived from meterology data and aircraft performance calculations.

cachestore¶: CacheStore for APCEMM run directories

compute_lagrangian_trajectories()¶

Calculate Lagrangian trajectories using a DryAdvection model.

Lagrangian trajectories provide the expected time-dependent location (longitude, latitude, and altitude) and orientation (azimuth) of contrails formed by the input source. This information is used to extract time series of meteorological profiles at the contrail location from input meteorology data, and to compute contrail-normal horizontal shear from horizontal winds.

The length of Lagrangian trajectories is set by the max_age parameter, and trajectories are integrated using a time step set by the dt_lagrangian parameter. Contrails are advected both horizontally and vertically, and a fixed sedimentation velocity (set by the sedimentation_rate parameter) can be included to represent contrail sedimentation.

Results of the trajectory calculation are attached to trajectories.

contrail¶: Paths to APCEMM netCDF output at prescribed time intervals

default_params¶: alias of APCEMMParams

property dynamic_yaml_params¶

Set of APCEMMInput attributes set dynamically by this model.

Other APCEMMInput attributes can be set statically by passing parameters in apcemm_input_params to the APCEMM constructor.

eval(source=None, **params)¶

Set up and run APCEMM simulations initialized at flight waypoints.

Simulates the formation and evolution of contrails from a Flight using the APCEMM plume model described in Fritz et. al. (2020) [Fritz et al., 2020].

Parameters:

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

Returns:

Flight | NoReturn – Flight with exit status of APCEMM simulations. Detailed APCEMM outputs are attached to model vortex and contrail attributes (see APCEMM notes for details).

References

[Fritz et al., 2020]

generate_apcemm_input(waypoint)¶

Generate APCEMM yaml and netCDF input files for a single waypoint.

For details about generated input files, see APCEMM notes.

Parameters:: waypoint (int) – Waypoint for which to generate input files.

long_name = 'Interface to APCEMM plume 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='z', standard_name='geopotential', long_name='Geopotential', level_type='isobaricInhPa', ecmwf_id=129, grib1_id=6, grib2_id=(0, 3, 4), units='m**2 s**-2', amip=None, description='Geopotential is the sum of the specific gravitational potential energy relative to the geoid and the specific centripetal potential energy.'), MetVariable(short_name='gh', standard_name='geopotential_height', long_name='Geopotential Height', level_type='isobaricInhPa', ecmwf_id=156, grib1_id=7, grib2_id=(0, 3, 5), units='m', amip='zg', description='Geopotential is the sum of the specific gravitational potential energy relative to the geoid and the specific centripetal potential energy. Geopotential height is the geopotential divided by the standard acceleration due to gravity. It is numerically similar to the altitude (or geometric height) and not to the quantity with standard name height, which is relative to the surface.')), 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.'))¶: 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 = 'apcemm'¶

process_apcemm_output()¶

Process APCEMM output.

After processing, a status column will be attached to source, and additional output data will be attached to vortex and contrail. For details about contents of APCEMM output files, see APCEMM notes.

run_apcemm(waypoints)¶

Run APCEMM over multiple waypoints.

Multiple waypoints will be processed in parallel if the APCEMM n_jobs parameter is set to a value larger than 1.

Parameters:: waypoints (list[int]) – List of waypoints at which to initialize simulations.

trajectories¶: Output from trajectory calculation

vortex¶: Time series output from the APCEMM early plume model