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`.
`ecmwf_met_variables`()	Return an ECMWF-specific list of required meteorology variables.
`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.
`generic_met_variables`()	Return a model-agnostic list of required meteorology variables.
`get_data_param`(other, key[, default, set_attr])	Get data from other source-compatible object with default set by model parameter key.
`get_source_param`(key[, default, set_attr])	Get source data with default set by parameter key.
`gfs_met_variables`()	Return a GFS-specific list of required meteorology variables.
`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_input_params`	Overridden APCEMM input parameters
`apcemm_path`	Path to APCEMM executable
`cachestore`	CacheStore for APCEMM run directories
`contrail`	Paths to APCEMM netCDF output at prescribed time intervals
`trajectories`	Output from trajectory calculation
`vortex`	Time series output from the APCEMM early plume model
`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

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.

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.

classmethod ecmwf_met_variables()¶

Return an ECMWF-specific list of required meteorology variables.

Returns:: tuple[MetVariable] – List of ECMWF-specific variants of required variables

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.

classmethod generic_met_variables()¶

Return a model-agnostic list of required meteorology variables.

Returns:: tuple[MetVariable] – List of model-agnostic variants of required variables

get_data_param(other, key, default=<object object>, *, set_attr=True)¶

Get data from other source-compatible object with default set by model parameter key.

Retrieves data with the following hierarchy:

other.data[key]. Returns np.ndarray | xr.DataArray.
other.attrs[key]
params[key]
default

In case 3., the value of params[key] is attached to other.attrs[key] unless set_attr is set to False.

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 other data, other attrs, or model params

Raises:

KeyError – Raises KeyError if key is not found in any location and default is not provided.