Python Interface

The documentation below provides details for several of the high-level functions wrapping the underlying Fortran code.

For more information about the low-level functions available in the pyrte_rrtmgp.kernels submodule, please go to Low-Level Kernel Modules.

pyrte_rrtmgp.rte module

RTE solver for pyRTE-RRTMGP.

class pyrte_rrtmgp.rte.OpticsTypes(*values)

Bases: StrEnum

Enumeration of available optics problem types.

This enum defines the different types of optics problems that can be solved with RRTMGP.

ABSORPTION = 'absorption': Absorption-only calculation

N_STREAM = 'n-stream': N-stream calculation

TWO_STREAM = 'two-stream': Two-stream approximation

class pyrte_rrtmgp.rte.RTEAccessor(ds: Dataset)

Bases: object

Functions for manipulating and solving radiation transfer problems.

add_to(other: Dataset, delta_scale: bool = False) → Dataset

Combine two sets of optical properties.

This function need not commute: it’s possible to add low spectral resolution optical properties to those at a higher spectral resolution but not the other way around.

Parameters:: other – Second set of optical properties to add.
Returns:: Combined optical properties.
Return type:: xr.Dataset

delta_scale_optical_props(optical_props: Dataset, forward_scattering: ndarray | None = None) → Dataset

Apply delta scaling to 2-stream optical properties.

Parameters:

optical_props – xarray Dataset containing tau, ssa, and g variables
forward_scattering – Optional array of forward scattering fraction
shape ((g**2 if not provided) Must have)

Raises:

ValueError – If forward_scattering array has incorrect dimensions or values
outside [0,1] –

solve(add_to_input: bool = True) → Dataset | None

Solve radiative transfer problem based on problem type.

Parameters:

problem_ds – Dataset containing problem definition and inputs
add_to_input – If True, add computed fluxes to input dataset. If False, return fluxes separately

Returns:

Dataset containing computed fluxes if add_to_input is False, None otherwise

pyrte_rrtmgp.config module

Default mappings for gas names, dimensions and variables used in RRTMGP.

This module contains dictionaries that map standard names to dataset-specific names for gases, dimensions and variables used in radiative transfer calculations.

pyrte_rrtmgp.config.DEFAULT_GAS_MAPPING: Final[Dict[str, list[str]]] = {'ccl4': ['ccl4', 'carbon_tetrachloride'], 'cf4': ['cf4', 'cf-4', 'carbon_tetrafluoride'], 'cfc11': ['cfc11', 'cfc-11', 'freon-11'], 'cfc12': ['cfc12', 'cfc-12', 'freon-12'], 'cfc22': ['cfc22', 'cfc-22', 'freon-22'], 'ch4': ['ch4', 'methane'], 'co': ['co', 'carbon_monoxide'], 'co2': ['co2', 'carbon_dioxide'], 'h2o': ['h2o', 'water_vapor', 'water'], 'hfc125': ['hfc125', 'hfc-125'], 'hfc134a': ['hfc134a', 'hfc-134a'], 'hfc143a': ['hfc143a', 'hfc-143a'], 'hfc23': ['hfc23', 'hfc-23'], 'hfc32': ['hfc32', 'hfc-32'], 'n2': ['n2', 'nitrogen'], 'n2o': ['n2o', 'nitrous_oxide'], 'no2': ['no2', 'nitrogen_dioxide'], 'o2': ['o2', 'oxygen'], 'o3': ['o3', 'ozone']}

A mapping of standard gas names to their corresponding RRTMGP-specific names.

Each key is a standard gas name (e.g., “h2o” for water vapor), and the value is a list of alternative names used in the RRTMGP model for the same gas.

pyrte_rrtmgp.cli module

Command line interface for pyRTE-RRTMGP.

pyrte_rrtmgp.cli.main() → None: Run the pyRTE-RRTMGP command line interface.

pyrte_rrtmgp.cli.run_code_coverage() → None: Run code coverage using pytest.

pyrte_rrtmgp.cli.run_examples() → None: Run example notebooks.

pyrte_rrtmgp.cli.run_tests() → None: Run tests using pytest.

pyrte_rrtmgp.rrtmgp module

Gas optics utilities for pyRTE-RRTMGP.

pyrte_rrtmgp.rrtmgp.AVOGAD: Final[float] = 6.02214076e+23: Avogadro’s number (molecules/mol)

class pyrte_rrtmgp.rrtmgp.BaseGasOptics(xarray_obj: Dataset, selected_gases: list[str] | None = None)

Bases: object

Base class for gas optics calculations.

This class provides common functionality for both longwave and shortwave gas optics calculations, including gas interpolation, optical depth computation, and handling of atmospheric conditions.

Parameters:

xarray_obj (xr.Dataset) – Dataset containing gas optics data
selected_gases (list[str] | None) – List of gases to include in calculations

Raises:

ValueError – If missing a required gas in the gas mapping (e.g. ‘co’, or ‘h2o’).

property available_gases: set[str]: Gases whose concentrations influence optical depth.

compute(atmosphere: Dataset, problem_type: OpticsTypes | None = None, gas_name_map: dict[str, str] | None = None, add_to_input: bool = True) → Dataset | None

Compute gas optics for given atmospheric conditions.

Parameters:

atmosphere – Dataset containing atmospheric conditions
problem_type – Type of radiative transfer problem to solve
gas_name_map – Optional mapping between gas names and variable names
add_to_input – Whether to add results to input dataset

Returns:

Dataset containing gas optics results if add_to_input=False, otherwise None

Raises:

ValueError – If problem_type is invalid

compute_problem(atmosphere: Dataset, gas_interpolation_data: Dataset) → Dataset

Compute optical properties for radiative transfer problem.

Parameters:

atmosphere – Dataset containing atmospheric conditions
gas_interpolation_data – Dataset containing interpolated gas data

Raises:

NotImplementedError – Must be implemented by subclasses

compute_sources(atmosphere: Dataset, gas_interpolation_data: Dataset | None = None) → Dataset

Compute radiation sources.

Parameters:

atmosphere – Dataset containing atmospheric conditions
gas_interpolation_data – Dataset containing interpolated gas data

Raises:

NotImplementedError – Must be implemented by subclasses

static extract_names(names: ndarray[tuple[Any, ...], dtype[_ScalarT]]) → tuple[str, ...]

Extract names from arrays, decoding and removing the suffix.

Parameters:: names – Array of encoded names
Returns:: Tuple of decoded and cleaned names

property flavors_sets: DataArray

Get the unique flavors from the k-distribution file.

Returns:: DataArray containing unique flavors

static get_col_dry(vmr_h2o: DataArray, atmosphere: Dataset, latitude: DataArray | None = None) → DataArray

Calculate the dry column of the atmosphere.

Parameters:

vmr_h2o – Water vapor volume mixing ratio
atmosphere – Dataset containing atmospheric conditions
latitude – Latitude of the location

Returns:

DataArray containing dry column of the atmosphere

get_gases_columns(atmosphere: Dataset, gas_name_map: dict[str, str]) → DataArray

Get gas columns from atmospheric conditions.

Parameters:

atmosphere – Dataset containing atmospheric conditions
gas_name_map – Mapping between gas names and variable names

Returns:

DataArray containing gas columns including dry air

get_idx_minor(minor_gases: Iterable[str]) → ndarray[tuple[Any, ...], dtype[int32]]

Get index of each minor gas in col_gas.

Parameters:: minor_gases – List of minor gases
Returns:: Array containing indices of minor gases

property gpoint_flavor: DataArray

Get the g-point flavors from the k-distribution file.

Each g-point is associated with a flavor, which is a pair of key species.

Returns:: DataArray containing g-point flavors

interpolate(atmosphere: Dataset, gas_name_map: dict[str, str]) → Dataset

Interpolate gas optics data to atmospheric conditions.

Parameters:

atmosphere – Dataset containing atmospheric conditions
gas_name_map – Mapping between gas names and variable names

Returns:

Dataset containing interpolated gas optics data

property press_max: float64: Minimum layer pressure for which gas optics data is valid.

property press_min: float64: Minimum layer pressure for which gas optics data is valid.

property required_gases: set[str]: Gases for which the concentration must be specified.

tau_absorption(atmosphere: Dataset, gas_interpolation_data: Dataset) → Dataset

Compute absorption optical depth.

Parameters:

atmosphere – Dataset containing atmospheric conditions
gas_interpolation_data – Dataset containing interpolated gas data

Returns:

Dataset containing absorption optical depth

property temp_max: float64: Minimum layer temperature for which gas optics data is valid.

property temp_min: float64: Minimum layer temperature for which gas optics data is valid.

validate_input_data(atmosphere: Dataset, gas_mapping: Dict[str, str]) → None

Validate input data: required information is present, values are valid.

Parameters:: atmosphere – Dataset containing atmospheric conditions
Raises:: ValueError if data is missing or has out-of-bounds values –

class pyrte_rrtmgp.rrtmgp.CloudOptics(file_path: str | None = None, cloud_optics_file: CloudOpticsFiles | None = None)

Bases: object

Accessor for computing cloud optical properties.

This accessor allows you to compute cloud optical properties using the compute_cloud_optics method.

Example usage:: dataset.compute_cloud_optics(cloud_properties)

Parameters:

cloud_properties (xr.Dataset) – Dataset containing cloud properties.
problem_type (str) – Type of problem to solve, either “two-stream” (default) or “absorption”.
add_to_input (bool) – Whether to add the computed properties to the input dataset (default: False).

Returns:

Dataset containing optical properties for both liquid and ice: phases.

Return type:

xr.Dataset

compute(cloud_properties: Dataset, problem_type: str = 'two-stream', add_to_input: bool = False) → Dataset

Compute cloud optical properties for liquid and ice clouds.

Parameters:

cloud_properties – Dataset containing cloud properties.
lw – Whether to compute liquid water phase (True) or ice water phase (False).
add_to_input (bool) – Whether to add the computed properties to the input dataset (default: False).

Returns:

Dataset containing optical properties for both liquid: and ice phases.

Return type:

xr.Dataset

property dei_max: float64: Maximum ice water effective diameter.

property dei_min: float64: Minimum ice water effective diameter.

property rel_max: float64: Maximum liquid water effective radius.

property rel_min: float64: Minimum liquid water effective radius.

class pyrte_rrtmgp.rrtmgp.GasOptics(file_path: str | None = None, gas_optics_file: GasOpticsFiles | None = None, selected_gases: list[str] | None = None)

Bases: object

Factory class that returns appropriate GasOptics based on dataset contents.

This class determines whether to return a longwave (LW) or shortwave (SW) gas optics accessor by checking for the presence of internal source variables in the dataset.

Example usage: dataset.compute_gas_optics(selected_gases=[“gas_a”, “gas_b”])

Parameters:

xarray_obj (xr.Dataset) – The xarray Dataset containing gas optics data
selected_gases (list[str] | None) – Optional list of gas names to include. If None, all gases in the dataset will be used.

pyrte_rrtmgp.rrtmgp.HELMERT1: Final[float] = 9.80665: Standard gravity at sea level

pyrte_rrtmgp.rrtmgp.HELMERT2: Final[float] = 0.02586: Gravity variation with latitude

class pyrte_rrtmgp.rrtmgp.LWGasOptics(xarray_obj: Dataset, selected_gases: list[str] | None = None)

Bases: BaseGasOptics

Accessor for internal (longwave) radiation sources.

This class handles gas optics calculations specific to longwave radiation, including computing absorption optical depths, Planck sources, and boundary conditions.

compute_planck(atmosphere: Dataset, gas_interpolation_data: Dataset) → Dataset

Compute Planck source terms for longwave radiation.

Parameters:

atmosphere – Dataset containing atmospheric conditions
gas_interpolation_data – Dataset containing interpolated gas properties

Returns:

Dataset containing Planck source terms including surface, layer and level: sources

compute_problem(atmosphere: Dataset, gas_interpolation_data: Dataset) → Dataset

Compute absorption optical depths for longwave radiation.

Parameters:

atmosphere – Dataset containing atmospheric conditions
gas_interpolation_data – Dataset containing interpolated gas properties

Returns:

Dataset containing absorption optical depths

compute_sources(atmosphere: Dataset, gas_interpolation_data: Dataset | None = None) → Dataset

Compute Planck source terms for longwave radiation.

Parameters:

atmosphere – Dataset containing atmospheric conditions
gas_interpolation_data – Dataset containing interpolated gas properties

Returns:

Dataset containing Planck source terms

pyrte_rrtmgp.rrtmgp.M_DRY: Final[float] = 0.028964: Dry air (molecular mass in kg/mol)

pyrte_rrtmgp.rrtmgp.M_H2O: Final[float] = 0.018016: Water vapor (molecular mass in kg/mol)

class pyrte_rrtmgp.rrtmgp.SWGasOptics(xarray_obj: Dataset, selected_gases: list[str] | None = None)

Bases: BaseGasOptics

Accessor for external (shortwave) radiation sources.

This class handles gas optics calculations specific to shortwave radiation, including computing absorption and Rayleigh scattering optical depths, solar sources, and boundary conditions.

compute_problem(atmosphere: Dataset, gas_interpolation_data: Dataset) → Dataset

Compute optical properties for shortwave radiation.

Parameters:

atmosphere – Dataset containing atmospheric conditions
gas_interpolation_data – Dataset containing interpolated gas properties

Returns:

Dataset containing optical properties (tau, ssa, g)

compute_sources(atmosphere: Dataset, gas_interpolation_data: Dataset | None = None) → DataArray

Compute solar source terms.

Parameters:

atmosphere – Dataset containing atmospheric conditions
*args – Variable length argument list
**kwargs – Arbitrary keyword arguments

Returns:

DataArray containing top-of-atmosphere solar source

tau_rayleigh(gas_interpolation_data: Dataset) → Dataset

Compute Rayleigh scattering optical depth.

Parameters:: gas_interpolation_data – Dataset containing interpolated gas properties
Returns:: Dataset containing Rayleigh scattering optical depth

pyrte_rrtmgp.rrtmgp.data_files module

Data download utilities and file name enums (lists) for pyRTE-RRTMGP.

class pyrte_rrtmgp.rrtmgp.data_files.AerosolOpticsFiles(*values)

Bases: StrEnum

Enumeration of default RRTMGP aerosol optics data files.

This enum defines the available pre-configured aerosol optics data files that can be used with RRTMGP. The files contain aerosol optical properties needed for radiative transfer calculations.

LW_MERRA = 'rrtmgp-aerosols-merra-lw.nc'

SW_MERRA = 'rrtmgp-aerosols-merra-sw.nc'

class pyrte_rrtmgp.rrtmgp.data_files.CloudOpticsFiles(*values)

Bases: StrEnum

Enumeration of default RRTMGP cloud optics data files.

This enum defines the available pre-configured cloud optics data files that can be used with RRTMGP. The files contain cloud optical properties needed for radiative transfer calculations.

LW_BND = 'rrtmgp-clouds-lw-bnd.nc': Longwave cloud optics file with band points

LW_G128 = 'rrtmgp-clouds-lw-g128.nc': Longwave cloud optics file with 128 g-points

LW_G256 = 'rrtmgp-clouds-lw-g256.nc': Longwave cloud optics file with 256 g-points

SW_BND = 'rrtmgp-clouds-sw-bnd.nc': Shortwave cloud optics file with band points

SW_G112 = 'rrtmgp-clouds-sw-g112.nc': Shortwave cloud optics file with 112 g-points

SW_G224 = 'rrtmgp-clouds-sw-g224.nc': Shortwave cloud optics file with 224 g-points

class pyrte_rrtmgp.rrtmgp.data_files.GasOpticsFiles(*values)

Bases: StrEnum

Enumeration of default RRTMGP gas optics data files.

This enum defines the available pre-configured gas optics data files that can be used with RRTMGP. The files contain absorption coefficients and other optical properties needed for radiative transfer calculations.

LW_G128 = 'rrtmgp-gas-lw-g128.nc': Longwave gas optics file with 128 g-points

LW_G256 = 'rrtmgp-gas-lw-g256.nc': Longwave gas optics file with 256 g-points

SW_G112 = 'rrtmgp-gas-sw-g112.nc': Shortwave gas optics file with 112 g-points

SW_G224 = 'rrtmgp-gas-sw-g224.nc': Shortwave gas optics file with 224 g-points

pyrte_rrtmgp.rrtmgp.data_files.download_rrtmgp_data() → str

Download and extract RRTMGP data files.

Downloads the RRTMGP data files from GitHub if not already present in the cache, verifies the checksum, and extracts the contents.

Returns:

Path to the extracted data directory

Return type:

str

Raises:

requests.exceptions.RequestException – If download fails
tarfile.TarError – If extraction fails

pyrte_rrtmgp.rrtmgp.data_files.get_cache_dir() → str

Get the system-specific cache directory for pyrte_rrtmgp data.

Returns:: Path to the cache directory
Return type:: str