Basic Usage

This section provides a brief overview of how to use the pyRTE-RRTMGP package. The example scripts and notebooks packaged with pyRTE-RRTMGP may also be useful (and are guaranteed to work with the current code).

The examples will likely supersede this documention over time.

RRTMGP and RTE

pyRTE-RRTMGP is a Python package that provides a Python interface to the RTE-RRTMGP software (Fortran). You can use this Python package to define a radiative transfer problem, compute gas and cloud optics, and solve the radiative transfer equations, using the same underlying code. See the paper Balancing Accuracy, Efficiency, and Flexibility in Radiation Calculations for Dynamical Models for more details about the Fortran code.

pyRTE-RRTMGP uses Dask for parallel computing, which can be useful for solving problems with large datasets on multi-core machines or clusters.

Defining and Solving Radiative Transfer Problems

A typical workflow with pyRTE-RRTMGP consists of the following steps:

1. Loading gas optics data by initializing the `GasOptics` class

Initializing the GasOptics class retrieves essential gas optics data for radiative transfer calculations. This data includes absorption coefficients and other optical properties for various atmospheric gases at different temperatures, pressures, and concentrations. See GasOptics for more details.

The package includes four default gas optics files, which can be accessed via the GasOpticsFiles enum:

Longwave:
- LW_G128: Longwave gas optics file with 128 g-points.
- LW_G256: Longwave gas optics file with 256 g-points.
Shortwave:
- SW_G112: Shortwave gas optics file with 112 g-points.
- SW_G224: Shortwave gas optics file with 224 g-points.

The data is loaded by passing one of the values of the enum to the GasOptics constructor. For example:

gas_optics_lw = rrtmgp.GasOptics(
    gas_optics_file=GasOpticsFiles.LW_G256
)

File names can also be supplied directly.

2. Loading cloud optics data by initializing the `CloudOptics` class

CloudOptics is the cloud equivalent of GasOptics. pyRTE-RRTMGP includes cloud optics files which can be accessed via the CloudOpticsFiles enum:

Longwave:
- LW_BND: Longwave cloud optics file with band points.
- LW_G128: Longwave cloud optics file with 128 g-points.
- LW_G256: Longwave cloud optics file with 256 g-points.
Shortwave:
- SW_BND: Shortwave cloud optics file with band points.
- SW_G112: Shortwave cloud optics file with 112 g-points.
- SW_G224: Shortwave cloud optics file with 224 g-points.

Loading the data is the same as for the gas optics:

cloud_optics_lw = rrtmgp.CloudOptics(
    cloud_optics_file=CloudOpticsFiles.LW_G256
)

3. Define the gas optics atmosphere

The atmosphere file defines the gas concentrations for each layer of the atmosphere in mole fractions. Gases are specified in terms of their (lowercase) chemical formula, with cfcX used for chlorofluorocarbon-X and hfcX for hydrofluorocarbon-X. Supported gases, i.e. those that will influence the calculation of optical properties, are available using the available_gases property of the gas optics, i.e.

gas_optics = rrtmgp.GasOptics(
    gas_optics_file=GasOpticsFiles.LW_G256
)
gas_optics.available_gases

Concentrations of some gases are required, those these can vary between the shortwave and longwave gas optics.

gas_optics = rrtmgp.GasOptics(
    gas_optics_file=GasOpticsFiles.LW_G256
)

gas_optics.required_gases

You can use any of the alternative names in your dataset, and use a mapping dictionary to map them to the correct gas. See DEFAULT_GAS_MAPPING for the default mapping.

If any of the gases are not present in the dataset, it will be set to zero. RRTMGP requires some gases to be specified; if are not present the package will raise an error.

The atmospheric input dataset also must contain the following core variables for computing gast optics:

temp_layer: Mean temperature within each atmospheric layer (K)
temp_level: Temperature at the boundaries between layers (K)
pres_layer: Mean pressure within each atmospheric layer (Pa)
pres_level: Pressure at the layer boundaries (Pa)

These variables must include layer and level dimensions, where the level dimension is one element larger than the layer dimension. Any additional dimensions in the dataset (e.g., spatial or temporal dimensions) will be automatically processed, with calculations performed for each combination of these dimensions.

For longwave radiation calculations, an additional variable is required:

surface_temperature: Skin temperature of the surface (K), used to compute the surface source of radiation

For shortwave radiation calculation the atmosphere may also contain an optional variable

total_solar_irradiance: Total solar irradiance at the top of the atmosphere (W/m2)

Neither surface_temperature nor total_solar_irradiance have a vertical dependence i.e. they should have no layer or level coordinate.

For instance, consider a dataset with these dimensions:

lat: Latitude coordinates
lon: Longitude coordinates
layer: Atmospheric layers
level: Layer boundaries
time: Timesteps

In this case, the radiative transfer calculations will be executed independently for each unique combination of latitude, longitude, and time, across all atmospheric levels.

4. Computing gas optics using `GasOptics.compute()`

Use a mapping dictionary to map gas names to their corresponding indices in the atmosphere data. For example:

gas_mapping = {
    "h2o": "water_vapor",
    "co2": "carbon_dioxide_GM",
    "o3": "ozone",
    "n2o": "nitrous_oxide_GM",
    "co": "carbon_monoxide_GM",
    "ch4": "methane_GM",
    "o2": "oxygen_GM",
    "n2": "nitrogen_GM",
}

With the atmosphere data and the gas mapping dictionary, you can compute the gas optics using the compute_gas_optics accessor.

gas_optics = gas_optics_lw.compute(
    atmosphere,
    gas_name_map=gas_mapping,
)

The gas optical properties also include the radiation source information.

5. Define the cloud optics

The cloud optics atmosphere requires the following variables in the input dataset for computing cloud optical properties:

lwp: Liquid water path (g/m²)
iwp: Ice water path (g/m²)
rel: Effective radius of liquid cloud particles (microns)
rei: Effective radius of ice cloud particles (microns)

They are defined in the layer dimension. Similar to the gas optics atmosphere, any additional dimensions will be processed independently.

6. Computing cloud optics using `CloudOptics.compute()`

You can compute the cloud optics using function compute() from pyrte_rrtmgp.rrtmgp.CloudOptics.

This function can handle two different types of problems:

ABSORPTION (longwave)
TWO_STREAM (shortwave)

cloud_optics = cloud_optics_lw.compute(
    atmosphere,
    problem_type=problem_type=OpticsTypes.ABSORPTION,
)

See pyrte_rrtmgp.rrtmgp_cloud_optics.CloudOpticsAccessor for more details.

7. Combining Cloud Optics with Gas Optics using `add_to()`.

To integrate cloud optical properties with gas optical properties use the add_to accessor. This adds the cloud optical properties to the pre-computed gas optical properties, including expanding from bands to g-points if needed.

For example, to combine the optical properties:

clouds_optical_props.rte.add_to(
    clear_sky_optical_props,
    delta_scale=True)

The clouds will be included in place over the clear sky optical properties.

8. Solving the radiative transfer equations using `solve()`

This function uses the optical properties of the atmosphere to solve the radiative transfer equations and compute the radiative fluxes.

fluxes = clouds_optical_props.rte.add_to(
    clear_sky_optical_props,
    delta_scale=True).\
    rte.solve(add_to_input = False)

See solve for more details.

Basic Usage

RRTMGP and RTE

Defining and Solving Radiative Transfer Problems

1. Loading gas optics data by initializing the GasOptics class

2. Loading cloud optics data by initializing the CloudOptics class

3. Define the gas optics atmosphere

4. Computing gas optics using GasOptics.compute()