source: LMDZ6/branches/LMDZ_ECRad/libf/phylmd/ecrad/README.md @ 5407

Last change on this file since 5407 was 4728, checked in by idelkadi, 14 months ago

Update of ecrad in the LMDZ_ECRad branch of LMDZ:

  • version 1.6.1 of ecrad
  • files are no longer grouped in the same ecrad directory.
  • the structure of ecrad offline is preserved to facilitate updating in LMDZ
  • cfg.bld modified to take into account the new added subdirectories.
  • the interface routines and those added in ecrad are moved to the phylmd directory
File size: 10.3 KB
Line 
1# ECRAD - ECMWF atmospheric radiation scheme
2
3This document last updated 9 June 2022
4
5Robin Hogan <r.j.hogan@ecmwf.int>
6
7For more complete information about compilation and usage of ecRad,
8please see the documentation on the
9[ecRad web site](https://confluence.ecmwf.int/display/ECRAD).
10
11
12## INTRODUCTION
13
14This package contains the offline version of a radiation scheme
15suitable for use in atmospheric weather and climate models.  The code
16is designed to be extensible and flexible.  For example, the gas
17optics, cloud optics and solver are completely separated (see
18`radiation/radiation_interface.F90` where they are called in sequence),
19thereby facilitating future changes where different gas models or
20solvers may be switched in and out independently. The offline code is
21parallelized using OpenMP.
22
23Five solvers are currently available:
24
251. The Monte Carlo Independent Column Approximation (McICA) of Pincus
26et al. (2003). This is is a now widely used method for treating cloud
27structure efficiently. The implementation in this package is more
28efficient than the one currently operational in the ECMWF model, and
29produces less noise in partially cloudy situations. Note that since
30McICA is stocastic, individual flux profiles using McICA may differ
31simply due to random variations in the sampling of the cloud field.
32
332. The Tripleclouds scheme of Shonk and Hogan (2008). This represents
34cloud structure by dividing each layer into three regions, one clear
35and two cloudy with different optical depth. It is somewhat slower
36than McICA but does not generate noise.
37
383. The Speedy Algorithm for Radiative Transfer through Cloud Sides
39(SPARTACUS) of Hogan et al. (JGR 2016). This is a method for
40efficiently treating 3D radiative effects associated with clouds. It
41uses the same differential equations proposed by Hogan and Shonk (JAS
422013), but solves them using a matrix exponential method that is much
43more elegant than their method, and is also here extended to the
44longwave (see Schaefer et al., JGR 2016).  It also incorporates the
45Tripleclouds methodology of Shonk and Hogan (2008) to represent cloud
46inhomogeneity.
47
484. A homogeneous (plane parallel) solver in which clouds are assumed
49to fill the gridbox horizontally.  This is useful for computing
50Independent Column Approximation benchmarks.
51
525. A "cloudless" solver if your focus is on clear skies.
53
54Two gas optics models are available:
55
561. The Rapid Radiative Transfer Model for GCMs (RRTMG), the
57implementation being that from the ECMWF Integrated Forecasting System
58(IFS).
59
602. The ECMWF Correlated k-Distribution (ecCKD) scheme (since ecRad
611.5), which uses a flexible discretization of the spectrum that is
62read from a file at run-time.
63
64
65## PACKAGE OVERVIEW
66
67The subdirectories are as follows:
68
69- `radiation` - the ecRad souce code
70
71- `ifsaux` - source code providing a (sometimes dummy) IFS environment
72
73- `ifsrrtm` - the IFS implementation of the RRTMG gas optics scheme
74
75- `utilities` - source code for useful utilities, such as reading netCDF
76       files
77
78- `drhook` - dummy version of the Dr Hook profiling system
79
80- `driver` - the source code for the offline driver program
81
82- `ifs` - slightly modified source files from the IFS that are used to provide inputs to
83        ecRad, but not used in this offline version except if you compile the ecrad_ifs_driver executable
84
85- `mod` - where Fortran module files are written
86
87- `lib` - where the static libraries are written
88
89- `bin` - where the executable ecrad is written
90
91- `data` - contains configuration data read at run-time
92
93- `test` - test cases including Matlab code to plot the outputs
94
95- `include` - automatically generated interface blocks for non-module routines
96
97- `practical` - exercises to get started with ecRad
98
99
100## TO COMPILE
101
1021. Ensure you have a reasonably recent Fortran compiler - it needs to
103support modules with `contains` and `procedure` statements for
104example.  Ensure you have the Fortran netCDF library installed
105(versions 3 or 4) and that the module file is compatible with your
106Fortran compiler.
107
1082. You can compile the code using
109
110       make PROFILE=<prof>
111
112   where `<prof>` is one of `gfortran`, `pgi`, `cray` or `intel`.
113   This will read the system-specific configurations from the file
114   `Makefile_include.<prof>`.  If you omit the `PROFILE=` option then
115   `gfortran` will be assumed. If you have a compiler other than these
116   then create such a file for your compiler following the example in
117   `Makefile_include.gfortran`. Two additional profiles are provided,
118   `ecmwf` which builds on the `gfortran` profile and `uor`
119   (University of Reading) which is built on the `pgi` profile.
120   
121   If the compile is successful then static libraries should appear in
122   the `lib` directory, and then the executable `bin/ecrad`.
123
1243. To clean-up, type `make clean`.  To build an unoptimized version
125   for debugging, you can do
126   
127       make PROFILE=<prof> DEBUG=1
128   
129   or you can specifically override the variables in `Makefile_include.<prof>`
130   using, for example
131   
132       make PROFILE=<prof> OPTFLAGS=-O0 DEBUGFLAGS="-g -pg"
133   
134   To compile in single precision add `SINGLE_PRECISION=1` to the
135   `make` command line.  To compile with the Dr Hook profiling system,
136   first install ECMWF's [fiat library]([ecRad web
137   site](https://github.com/ecmwf-ifs/fiat), then add
138   `FIATDIR=/path/to/fiat` to the `make` command line, such that the
139   files `$FIATDIR/lib/libfiat.so` and
140   `$FIATDIR/module/fiat/yomhook.mod` can be found at build time.
141   
142
143## TO TEST
144
145The offline driver is run via
146
147    ecrad <namelist.nam> <input_file.nc> <output_file.nc>
148
149where the radiation scheme is configured using the Fortran namelist
150file `<namelist.nam>`, and the inputs and outputs are in netCDF
151format.
152
153The `practical` directory contains a set of practical exercises to
154help new users become familiar with the capabilities of ecRad. Start
155by reading the instructions in `practical/ecrad_practical.pdf`.
156
157The `test/ifs` directory contains a pole-to-pole slice of
158low-resolution IFS model data in a form to use as input to the offline
159version of ecRad. It includes aerosols extracted from the CAMS
160climatology used operationally since IFS Cycle 43R3. Typing `make
161test` in this directory runs a number of configurations of ecRad
162described in the Makefile. The Matlab script `plot_ifs.m` can be used
163to visualize the results. The file
164`ecrad_meridian_default_out_REFERENCE.nc` contains a reference version
165of the output file `ecrad_meridian_default_out.nc` (case "a"), which
166you can compare to be sure your compilation is working as
167expected. This case has essentially been superceded by the slice in the
168`practical` directory.
169
170The `test/i3rc` directory contains the 1D profile of the I3RC cumulus
171test case used by Hogan et al. (2016). Typing `make test` in this
172directory runs the various 1D and 3D configurations of ecRad. The
173Matlab script `plot_i3rc.m` can then be used to visualize the results,
174reproducing three of the figures from Hogan et al. (2016). Note that
175you will need to ensure that a reasonably up-to-date version of the
176`nco` tools are available and in your path.  This test involves
177running the duplicate_profiles.sh script, which duplicates the single
178profile in `i3rc_mls_cumulus.nc`, each with a different solar zenith
179angle.
180
181The `test/surface` directory contains tests of the surface tile types,
182although this is under development and so nothing here is guaranteed
183to work.
184
185Alternatively, type `make test` in the top-level directory to run all
186cases.
187
188In addition to writing the output file, a file containing the
189intermediate radiative properties of the atmosphere for each g-point
190can be stored in `radiative_properties.nc` (edit the config namelist to
191enable this), but note that the g-points have been reordered in
192approximate order of optical depth if the SPARTACUS solver is chosen.
193
194
195## LICENCE
196
197(C) Copyright 2014- ECMWF.
198
199This software is licensed under the terms of the Apache Licence Version 2.0
200which can be obtained at http://www.apache.org/licenses/LICENSE-2.0.
201
202In applying this licence, ECMWF does not waive the privileges and immunities
203granted to it by virtue of its status as an intergovernmental organisation
204nor does it submit to any jurisdiction.
205Copyright statements are given in the file NOTICE.
206
207The ifsrrtm directory of this package includes a modified version of
208the gas optics part of the Rapid Radiative Transfer Model for GCMS
209(RRTMG).  RRTMG was developed at Atmospheric & Environmental Research
210(AER), Inc., Lexington, Massachusetts and is available under the
211"3-clause BSD" license; for details, see ifsrrtm/AER-BSD3-LICENSE.
212
213
214## PUBLICATIONS
215
216The ecRad radiation scheme itself is described here:
217
218 - Hogan, R. J., and A. Bozzo, 2018: A flexible and efficient radiation
219scheme for the ECMWF model.  J. Adv. Modeling Earth Syst., 10, 1990-2008,
220doi:10.1029/2018MS001364.
221
222 - Hogan, R. J., and A. Bozzo, 2016: ECRAD: A new radiation scheme for
223the IFS. ECMWF Technical Memorandum number 787, 35pp:
224http://www.ecmwf.int/en/elibrary/16901-ecrad-new-radiation-scheme-ifs
225
226A two-part paper is published in Journal of Geophysics Research
227describing the SPARTACUS technique:
228
229 - Schäfer, S. A. K., R. J. Hogan, C. Klinger, J.-C. Chiu and B. Mayer,
2302016: Representing 3D cloud-radiation effects in two-stream schemes: 1. Longwave considerations and effective cloud edge length.
231J. Geophys. Res., 121, 8567-8582.
232http://www.met.reading.ac.uk/~swrhgnrj/publications/spartacus_part1.pdf
233
234 - Hogan, R. J., S. A. K. Schäfer, C. Klinger, J.-C. Chiu and B. Mayer,
2352016: Representing 3D cloud-radiation effects in two-stream schemes: 2. Matrix formulation and broadband evaluation. J. Geophys. Res., 121,
2368583-8599.
237http://www.met.reading.ac.uk/~swrhgnrj/publications/spartacus_part2.pdf
238
239More recent developments on the shortwave SPARTACUS solver, available
240since ecRad 1.1.10, are described here:
241
242 - Hogan, R. J., M. D. Fielding, H. W. Barker, N. Villefranque and
243S. A. K. Schäfer, 2019: Entrapment: An important mechanism to explain
244the shortwave 3D radiative effect of clouds. J. Atmos. Sci., 76,
2452123–2141.
246
247The ecCKD gas optics scheme is described here:
248
249 - Hogan, R. J., and M. Matricardi, 2022: a tool for generating fast
250k-distribution gas-optics models for weather and climate
251applications. J. Adv. Modeling Earth Sys., in review.
252
253
254## CONTACT
255
256Please email Robin Hogan <r.j.hogan@ecmwf.int> with any queries or bug
257fixes, but note that ECMWF does not commit to providing support to
258users of this software.
Note: See TracBrowser for help on using the repository browser.