ecRad

The ECMWF atmospheric radiation scheme

For more complete information about compilation and usage of ecRad, please see the documentation on the ecRad web site.

Introduction

This package contains the offline version of a radiation scheme suitable for use in atmospheric weather and climate models. The code is designed to be extensible and flexible. For example, the gas optics, cloud optics and solver are completely separated (see radiation/radiation_interface.F90 where they are called in sequence), thereby facilitating future changes where different gas models or solvers may be switched in and out independently. The offline code is parallelized using OpenMP.

Five solvers are currently available:

1. The Monte Carlo Independent Column Approximation (McICA) of Pincus et al. (2003). This is is a now widely used method for treating cloud structure efficiently. The implementation in this package is more efficient than the one currently operational in the ECMWF model, and produces less noise in partially cloudy situations. Note that since McICA is stocastic, individual flux profiles using McICA may differ simply due to random variations in the sampling of the cloud field.

2. The Tripleclouds scheme of Shonk and Hogan (2008). This represents cloud structure by dividing each layer into three regions, one clear and two cloudy with different optical depth. It is somewhat slower than McICA but does not generate noise.

3. The Speedy Algorithm for Radiative Transfer through Cloud Sides (SPARTACUS) of Hogan et al. (JGR 2016). This is a method for efficiently treating 3D radiative effects associated with clouds. It uses the same differential equations proposed by Hogan and Shonk (JAS 2013), but solves them using a matrix exponential method that is much more elegant than their method, and is also here extended to the longwave (see Schaefer et al., JGR 2016). It also incorporates the Tripleclouds methodology of Shonk and Hogan (2008) to represent cloud inhomogeneity.

4. A homogeneous (plane parallel) solver in which clouds are assumed to fill the gridbox horizontally. This is useful for computing Independent Column Approximation benchmarks.

5. A "cloudless" solver if your focus is on clear skies.

Two gas optics models are available:

1. The Rapid Radiative Transfer Model for GCMs (RRTMG), the implementation being that from the ECMWF Integrated Forecasting System (IFS).

2. The ECMWF Correlated k-Distribution (ecCKD) scheme (since ecRad 1.5), which uses a flexible discretization of the spectrum that is read from a file at run-time.

Package overview

The subdirectories are as follows:

• radiation - the ecRad souce code

• ifsaux - source code providing a (sometimes dummy) IFS environment

• ifsrrtm - the IFS implementation of the RRTMG gas optics scheme

• utilities - source code for useful utilities, such as reading netCDF files

• drhook - dummy version of the Dr Hook profiling system

• driver - the source code for the offline driver program

• ifs - slightly modified source files from the IFS that are used to provide inputs to ecRad, but not used in this offline version except if you compile the ecradifsdriver executable

• mod - where Fortran module files are written

• lib - where the static libraries are written

• bin - where the executable ecrad is written

• data - contains configuration data read at run-time

• test - test cases including Matlab code to plot the outputs

• include - automatically generated interface blocks for non-module routines

• practical - exercises to get started with ecRad

Compilation

1. Ensure you have a reasonably recent Fortran compiler - it needs to support modules with contains and procedure statements for example. Ensure you have the Fortran netCDF library installed (versions 3 or 4) and that the module file is compatible with your Fortran compiler.

2. You can compile the code using

   make PROFILE=

where <prof> is one of gfortran, pgi, cray or intel. This will read the system-specific configurations from the file Makefile_include.<prof>. If you omit the PROFILE= option then gfortran will be assumed. If you have a compiler other than these then create such a file for your compiler following the example in Makefile_include.gfortran. Two additional profiles are provided, ecmwf which builds on the gfortran profile and uor (University of Reading) which is built on the pgi profile.

If the compile is successful then static libraries should appear in the lib directory, and then the executable bin/ecrad.

1. To clean-up, type make clean. To build an unoptimized version for debugging, you can do

   make PROFILE= DEBUG=1

or you can specifically override the variables in Makefile_include.<prof> using, for example

   make PROFILE=<prof> OPTFLAGS=-O0 DEBUGFLAGS="-g -pg"

To compile in single precision add SINGLE_PRECISION=1 to the make command line. To compile with the Dr Hook profiling system, first install ECMWF's [fiat library](ecRad web site, then add FIATDIR=/path/to/fiat to the make command line, such that the files $FIATDIR/lib/libfiat.so and $FIATDIR/module/fiat/yomhook.mod can be found at build time.

Testing

The offline driver is run via

ecrad <namelist.nam> <input_file.nc> <output_file.nc>

where the radiation scheme is configured using the Fortran namelist file <namelist.nam>, and the inputs and outputs are in netCDF format.

The practical directory contains a set of practical exercises to help new users become familiar with the capabilities of ecRad. Start by reading the instructions in practical/ecrad_practical.pdf.

The test/ifs directory contains a pole-to-pole slice of low-resolution IFS model data in a form to use as input to the offline version of ecRad. It includes aerosols extracted from the CAMS climatology used operationally since IFS Cycle 43R3. Typing make test in this directory runs a number of configurations of ecRad described in the Makefile. The Matlab script plot_ifs.m can be used to visualize the results. The file ecrad_meridian_default_out_REFERENCE.nc contains a reference version of the output file ecrad_meridian_default_out.nc (case "a"), which you can compare to be sure your compilation is working as expected. This case has essentially been superceded by the slice in the practical directory.

The test/i3rc directory contains the 1D profile of the I3RC cumulus test case used by Hogan et al. (2016). Typing make test in this directory runs the various 1D and 3D configurations of ecRad. The Matlab script plot_i3rc.m can then be used to visualize the results, reproducing three of the figures from Hogan et al. (2016). Note that you will need to ensure that a reasonably up-to-date version of the nco tools are available and in your path. This test involves running the duplicateprofiles.sh script, which duplicates the single profile in `i3rcmls_cumulus.nc`, each with a different solar zenith angle.

The test/surface directory contains tests of the surface tile types, although this is under development and so nothing here is guaranteed to work.

Alternatively, type make test in the top-level directory to run all cases.

In addition to writing the output file, a file containing the intermediate radiative properties of the atmosphere for each g-point can be stored in radiative_properties.nc (edit the config namelist to enable this), but note that the g-points have been reordered in approximate order of optical depth if the SPARTACUS solver is chosen.

CMake BUILD PROCEDURE

The ecRad radiation scheme can also be built using CMake and ecbuild. This only requires CMake to be installed, if ecbuild cannot be found a compatible version will automatically be downloaded.

CMake will perform an out-of-tree build, i.e., put all build artifacts into a different directory than the source files. With the code checked out into <ecrad directory>, the CMake build procedure is as follows:

sh cmake -B <build-directory> -S <ecrad directory> cmake --build <build-directory>

Optionally, the first command can be amended with -Dfiat_ROOT=<fiat build dir> to build against the optional fiat build dependency. Other build options are:

• DOUBLE_PRECISION: build double-precision version (default: ON)
• SINGLE_PRECISION: build single-precision version (default: OFF)
• OMP: build with OpenMP thread-parallelism if supported by the compiler (default: ON)

The options can be enabled/disabled by providing -DENABLE_<OPTION>=ON|OFF to the first command.

CMake comes with a test suite that runs a set of configurations of ecrad. Execute the tests after successful compilation using:

sh cd <build-dir> ctest

Licence

(C) Copyright 2014- ECMWF.

This software is licensed under the terms of the Apache Licence Version 2.0 which can be obtained at http://www.apache.org/licenses/LICENSE-2.0.

In applying this licence, ECMWF does not waive the privileges and immunities granted to it by virtue of its status as an intergovernmental organisation nor does it submit to any jurisdiction. Copyright statements are given in the file NOTICE.

The ifsrrtm directory of this package includes a modified version of the gas optics part of the Rapid Radiative Transfer Model for GCMS (RRTMG). RRTMG was developed at Atmospheric & Environmental Research (AER), Inc., Lexington, Massachusetts and is available under the "3-clause BSD" license; for details, see ifsrrtm/AER-BSD3-LICENSE.

Contributing

Contributions to ECRAD are welcome. In order to do so, please open an issue where a feature request or bug can be discussed. Then create a pull request with your contribution and sign the contributors license agreement (CLA).

Publications

The ecRad radiation scheme itself is described here:

• Hogan, R. J., and A. Bozzo, 2018: A flexible and efficient radiation scheme for the ECMWF model. J. Adv. Modeling Earth Syst., 10, 1990-2008, doi:10.1029/2018MS001364.

• Hogan, R. J., and A. Bozzo, 2016: ECRAD: A new radiation scheme for the IFS. ECMWF Technical Memorandum number 787, 35pp: http://www.ecmwf.int/en/elibrary/16901-ecrad-new-radiation-scheme-ifs

A two-part paper is published in Journal of Geophysics Research describing the SPARTACUS technique:

• Schäfer, S. A. K., R. J. Hogan, C. Klinger, J.-C. Chiu and B. Mayer, 2016: Representing 3D cloud-radiation effects in two-stream schemes: 1. Longwave considerations and effective cloud edge length. J. Geophys. Res., 121, 8567-8582. http://www.met.reading.ac.uk/~swrhgnrj/publications/spartacus_part1.pdf

• Hogan, R. J., S. A. K. Schäfer, C. Klinger, J.-C. Chiu and B. Mayer, 2016: Representing 3D cloud-radiation effects in two-stream schemes: 2. Matrix formulation and broadband evaluation. J. Geophys. Res., 121, 8583-8599. http://www.met.reading.ac.uk/~swrhgnrj/publications/spartacus_part2.pdf

More recent developments on the shortwave SPARTACUS solver, available since ecRad 1.1.10, are described here:

• Hogan, R. J., M. D. Fielding, H. W. Barker, N. Villefranque and S. A. K. Schäfer, 2019: Entrapment: An important mechanism to explain the shortwave 3D radiative effect of clouds. J. Atmos. Sci., 76, 2123–2141.

The ecCKD gas optics scheme is described here:

• Hogan, R. J., and M. Matricardi, 2022: a tool for generating fast k-distribution gas-optics models for weather and climate applications. J. Adv. Modeling Earth Sys., in review.