emc2.core.model.E3SMv3

class emc2.core.model.E3SMv3(file_path, time_range=None, load_processed=False, time_dim='time', appended_str=False, all_appended_in_lat=False, single_ice_class=True, include_rain_in_rt=False, mcphys_scheme='P3', instrument=None, use_hybrid_scat=False)

This loads an E3SMv3 simulation output with all of the necessary parameters for EMC^2 to run. Note that a p3_kws attribute is added to this Model sub-class to host the p3-specific namelist.

Parameters:

file_path: str

Path to an E3SMv3 simulation.

time_range: tuple, list, or array, typically in datetime64 format

Two-element array with starting and ending of time range.

load_processed: bool

If True, treating the ‘file_path’ variable as an EMC2-processed dataset; thus skipping appended string removal and dimension stacking, which are typically part of pre-processing.

time_dim: str

Name of the time dimension. Typically “time” or “ncol”.

appended_str: bool

If True, removing appended strings added to fieldnames and coordinates during post-processing (e.g., in cropped regions from global simualtions).

all_appended_in_lat: bool

If True using only the appended str portion to the lat_dim. Otherwise, combining the appended str from both the lat and lon dims (relevant if appended_str is True).

single_ice_class: bool

If True, assuming model microphysics incorporate a single ice class (e.g., in P3 implemented in E3SMv3).

include_rain_in_rt: bool

If True, including the rain class (pl) in the forward calculations. By default, set to False given that the rain class is excluded from the E3SM radiative scheme calculations.

mcphys_scheme: str

Name of the microphysics scheme used by the model. Current options are:

instrument: :func:`emc2.core.Instrument` class

An Instrument object, the LUTs of which are used here to calculate ice PSD parameters, to save computation time in subsequent processing.

use_hybrid_scat: bool or int

If True or > 0 taking a hybrid approach, i.e., using beta_p and alpha_p of (per calculation approach): (1) microphysics: equivalent volume spheres (with D still being the max dimensions per P3 approach). (2) radiation: (== 1) pure radiation approach, i.e., derive A_hyd from r_eff and subcolumn q_i

(== 2) equivalent volume spheres (as in the microphysics approach) or (Mie) sphere

assumptions while still being faithful to the PSD information from model output

Note that we do not use here equivalent volume to surface area approach per D. Mitchell because the diameters and hence surface areas are non-monotonic, which introduces some weird behavior. The effect of this approach is to reduce potentially overestimated lidar variables (think about the implications for E3SM optics…) and radar variables, though to a lesser extent. Note #2: This boolean does not affect the terminal velocity calculations, which are based on the m-D,A-D information. This, together with the non-equivalent V/A renders this approach “hybrid” and increases the gap between microphysics and radiation. If False or == 0 (default), using full P3 approach, i.e., consistent treatment of ice microphysics and radiation, to a large extent at the very least.

__init__(file_path, time_range=None, load_processed=False, time_dim='time', appended_str=False, all_appended_in_lat=False, single_ice_class=True, include_rain_in_rt=False, mcphys_scheme='P3', instrument=None, use_hybrid_scat=False)

This loads an E3SMv3 simulation output with all of the necessary parameters for EMC^2 to run. Note that a p3_kws attribute is added to this Model sub-class to host the p3-specific namelist.

Parameters:

file_path: str

Path to an E3SMv3 simulation.

time_range: tuple, list, or array, typically in datetime64 format

Two-element array with starting and ending of time range.

load_processed: bool

If True, treating the ‘file_path’ variable as an EMC2-processed dataset; thus skipping appended string removal and dimension stacking, which are typically part of pre-processing.

time_dim: str

Name of the time dimension. Typically “time” or “ncol”.

appended_str: bool

If True, removing appended strings added to fieldnames and coordinates during post-processing (e.g., in cropped regions from global simualtions).

all_appended_in_lat: bool

If True using only the appended str portion to the lat_dim. Otherwise, combining the appended str from both the lat and lon dims (relevant if appended_str is True).

single_ice_class: bool

If True, assuming model microphysics incorporate a single ice class (e.g., in P3 implemented in E3SMv3).

include_rain_in_rt: bool

If True, including the rain class (pl) in the forward calculations. By default, set to False given that the rain class is excluded from the E3SM radiative scheme calculations.

mcphys_scheme: str

Name of the microphysics scheme used by the model. Current options are:

instrument: :func:`emc2.core.Instrument` class

An Instrument object, the LUTs of which are used here to calculate ice PSD parameters, to save computation time in subsequent processing.

use_hybrid_scat: bool or int

If True or > 0 taking a hybrid approach, i.e., using beta_p and alpha_p of (per calculation approach): (1) microphysics: equivalent volume spheres (with D still being the max dimensions per P3 approach). (2) radiation: (== 1) pure radiation approach, i.e., derive A_hyd from r_eff and subcolumn q_i

(== 2) equivalent volume spheres (as in the microphysics approach) or (Mie) sphere

assumptions while still being faithful to the PSD information from model output

Note that we do not use here equivalent volume to surface area approach per D. Mitchell because the diameters and hence surface areas are non-monotonic, which introduces some weird behavior. The effect of this approach is to reduce potentially overestimated lidar variables (think about the implications for E3SM optics…) and radar variables, though to a lesser extent. Note #2: This boolean does not affect the terminal velocity calculations, which are based on the m-D,A-D information. This, together with the non-equivalent V/A renders this approach “hybrid” and increases the gap between microphysics and radiation. If False or == 0 (default), using full P3 approach, i.e., consistent treatment of ice microphysics and radiation, to a large extent at the very least.

Methods

__init__(file_path[, time_range, ...])	This loads an E3SMv3 simulation output with all of the necessary parameters for EMC^2 to run.
calc_mu_n0_from_lambda(lambda_in)	Calculate the Gamma PSD shape parameter (mu) and normalized n0 from the given lambda following E3SMv3 processing (see: /E3SM/components/eam/tools/create_p3_lookupTable/create_p3_lookupTable_1.f90-v4.1).
check_and_stack_time_lat_lon([...])	Stack the time dim together with the lat and lon dims (if the lat and/or lon dims are longer than 1) to enable EMC^2 processing of regional model output.
finalize_subcol_fields([more_fieldnames])	Remove all zero values from subcolumn output fields enabling better visualization.
interp_p3_ice_psd_params_to_grid(scat_file)	Sets the ice particle size distribution (PSD) parameters via interpolation using scattering file data and optional input data range limitation.
limit_input_data_to_p3_lut_range(scat_file)	Adjusts the input data to ensure it falls within the valid range defined by the provided (P3) lookup table (LUT).
load_subcolumns_from_netcdf(file_name)	Load all of the subcolumn data from a previously saved netCDF file.
permute_dims_for_processing([base_order, ...])	Reorder dims for consistent processing such that the order is: subcolumn x time x height.
remove_appended_str([all_appended_in_lat])	Remove appended strings from xr.Dataset coords and fieldnames based on lat/lon coord names (typically required when using post-processed output data files).
remove_subcol_fields([cloud_class])	Remove all subcolumn output fields for the given cloud class to save memory (mainly releveant for CESM and E3SM).
set_array_to_valid_range(arr_in, grid_in)	Adjusts the values in the input array to ensure they fall within the valid range defined by the minimum and maximum values of the grid array.
set_hyd_types(hyd_types)
subcolumns_to_netcdf(file_name)	Saves all of the simulated subcolumn parameters to a netCDF file.
unstack_time_lat_lon([order_dim, ...])	Unstack the time, lat, and lon dims if they were previously stacked together (self.stacked_time_dim is not None).

Attributes

hydrometeor_classes	The list of hydrometeor classes.
num_hydrometeor_classes	The number of hydrometeor classes used
num_subcolumns	Gets the number of subcolumns in the model.