From 16e50beda1ff0f89876c0c02902fbc4f0b3289f0 Mon Sep 17 00:00:00 2001 From: Ruth Geen Date: Wed, 12 Aug 2020 15:51:23 +0100 Subject: [PATCH] Add documentation for RRTM Radiation --- docs/source/modules/index.rst | 1 + docs/source/modules/rrtm_radiation.rst | 273 +++++++++++++++++++++++++ docs/source/references.rst | 13 ++ 3 files changed, 287 insertions(+) create mode 100644 docs/source/modules/rrtm_radiation.rst diff --git a/docs/source/modules/index.rst b/docs/source/modules/index.rst index 1621c7fc9..557dee7e2 100644 --- a/docs/source/modules/index.rst +++ b/docs/source/modules/index.rst @@ -12,3 +12,4 @@ Components of Isca output convection_simple_betts_miller socrates + rrtm_radiation diff --git a/docs/source/modules/rrtm_radiation.rst b/docs/source/modules/rrtm_radiation.rst new file mode 100644 index 000000000..3314a0dab --- /dev/null +++ b/docs/source/modules/rrtm_radiation.rst @@ -0,0 +1,273 @@ +.. DO NOT MODIFY THIS FILE UNLESS YOU ARE A CORE MAINTAINER OF ISCA! + +.. + This is a reStructuredText template file for creating + a new documentation entry for the Isca model. + + Please make a copy of this file with the appropriate file name and place it + to the appropriate location within docs/source/ and start writing. + Once you are done, remove all the comments from your .rst file. + + Here is a guide on reST formatting: + https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html + + +RRTM Radiation Scheme Interface +=================================== + +Summary +------- + +RRTM (Rapid Radiative Transfer Model) is a multiband correlated-k radiative transfer scheme, described in [MlawerEtAl1997]_ and [CloughEtAl2005]_. + +The correlated-k method, with k being the absorption coefficient, is a means to efficiently calculate radiative transfer over a broad spectral range by collecting wave number intervals with similar spectral properties and by supposing that these spectral properties are correlated from one level to another. A relatively small set of absorption coefficients can then be chosen to be representative of the absorption coefficients for all frequencies, leading to an enormous speed-up over line-by-line calculations and much better accuracy than traditional band methods that more simplistically just group together similar wave numbers. The implementation of this scheme in Isca largely follows that of Jucker and Gerber (2017) in the MiMA model (see [VallisEtAl2018]_). + +The fortran code is found in the folder ``src/atmos_param/rrtm_radiation/`` +Specifically, the code is driven from ``src/atmos_param/rrtm_radiation/rrtm_radiation.f90`` + +Namelist options +---------------- + +The RRTM namelist ``rrtm_radiation_nml`` can be found at ``src/atmos_param/rrtm_radiation/rrtm_radiation.f90``. + +Radiation options +^^^^^^^^^^^^^^^^^ + +Here are some options to set incoming radiation: + ++----------------------------+----------+-----------------------------------------------------------------------------------------+ +| Name | Default | Description | ++============================+==========+=========================================================================================+ +|``solday`` | 0 | If ``solday>0``, do perpetual run corresponding to day of the year = solday in | +| | | [0, days per year] | ++----------------------------+----------+-----------------------------------------------------------------------------------------+ +|``do_rad_time_avg`` | True | Average ``coszen`` for shortwave radiation over ``dt_rad`` | ++----------------------------+----------+-----------------------------------------------------------------------------------------+ +|``equinox_day`` | 0.75 | Fraction of the year defining NH autumn equinox in ``[0, 1]`` | ++----------------------------+----------+-----------------------------------------------------------------------------------------+ +|``solr_cnst`` | 1368.22 | solar constant (units: Wm :math:`^{-2}`) | ++----------------------------+----------+-----------------------------------------------------------------------------------------+ +|``frierson_solar_rad`` | False | Options for annual-mean incoming solar, as prescribed in Frierson's grey scheme | ++----------------------------+----------+-----------------------------------------------------------------------------------------+ +|``del_sol`` | 0.95 | Latitudinal variation of shortwave radiation, as prescribed in Frierson's grey scheme | ++----------------------------+----------+-----------------------------------------------------------------------------------------+ +|``del_sw`` | 0 | Latitudinal variation of shortwave radiation, as prescribed in Frierson's grey scheme | ++----------------------------+----------+-----------------------------------------------------------------------------------------+ +|``slowdown_rad`` | 1 | Factor to simulate slower seasonal cycle: >1 means faster, <1 slower. NB. This can also | +| | | be achieved by using the ``orbital_period`` option in ``constants_nml`` | ++----------------------------+----------+-----------------------------------------------------------------------------------------+ +|``use_dyofyr`` | False | Option to use day of the year to compute the Earth-Sun distance. NB. This is done | +| | | within RRTM, and assumes 365 days per year! | ++----------------------------+----------+-----------------------------------------------------------------------------------------+ +|``solrad`` | 1 | Sets Earth-Sun distance if ``use_dyofyr`` is false. | ++----------------------------+----------+-----------------------------------------------------------------------------------------+ + + +The following namelist variables set radiation time stepping and spatial sampling: + ++----------------------------+----------+---------------------------------------------------------------------------------------------------------+ +| Name | Default | Description | ++============================+==========+=========================================================================================================+ +| ``dt_rad`` | 0 | Radiation timestep - every step if ``dt_rad0, replace everything above this value with 0 | ++----------------------------+-------------+---------------------------------------------------------------------------------------------------------+ +| ``do_read_sw_flux`` | False | Read SW surface fluxes from external file? | ++----------------------------+-------------+---------------------------------------------------------------------------------------------------------+ +| ``sw_flux_file`` | 'sw_flux' | File name to read SW surface fluxes from | ++----------------------------+-------------+---------------------------------------------------------------------------------------------------------+ +| ``do_read_lw_flux`` | False | Read LW surface fluxes from external file? | ++----------------------------+-------------+---------------------------------------------------------------------------------------------------------+ +| ``lw_flux_file`` | 'lw_flux' | File name to read LW surface fluxes from | ++----------------------------+-------------+---------------------------------------------------------------------------------------------------------+ + + +While clouds are not currently incorporated into RRTM within Isca, the following options allow the albedo to be modified based on where precipitation is falling: + ++----------------------------+----------+---------------------------------------------------------------------------------------------------------+ +| Name | Default | Description | ++============================+==========+=========================================================================================================+ +| ``do_precip_albedo`` | False | Modify albedo depending on large scale precipitation | ++----------------------------+----------+---------------------------------------------------------------------------------------------------------+ +| ``precip_albedo_mode`` | 'full' | Select whether to use precipitation from only large scale condensation ('lscale'), | +| | | only convection ('conv') or both ('full') | ++----------------------------+----------+---------------------------------------------------------------------------------------------------------+ +| ``precip_albedo`` | 0.35 | Set cloud albedo if ``do_precip_albedo`` is True | ++----------------------------+----------+---------------------------------------------------------------------------------------------------------+ +| ``precip_lat`` | 0.0 | Apply ``precip_albedo`` poleward of this latitude | ++----------------------------+----------+---------------------------------------------------------------------------------------------------------+ + + +Some safety boundaries: + ++----------------------------+----------+---------------------------------------------------------------------------------------------------------+ +| Name | Default | Description | ++============================+==========+=========================================================================================================+ +| ``h2o_lower_limit`` | 2.e-7 | Set lower limit on water vapor to be seen by RRTM, input values below this are replaced by this value | ++----------------------------+----------+---------------------------------------------------------------------------------------------------------+ +| ``temp_lower_limit`` | 100 | Set lower limit on temperature to be seen by RRTM, input values below this are replaced by this value | ++----------------------------+----------+---------------------------------------------------------------------------------------------------------+ +| ``temp_upper_limit`` | 370 | Set upper limit on temperature to be seen by RRTM, input values above this are replaced by this value | ++----------------------------+----------+---------------------------------------------------------------------------------------------------------+ + + +CO2, ozone and other gases +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Isca does not include advection or chemistry of ozone and carbon dioxide. Values of these can be prescribed using the following options: + ++----------------------------+----------+---------------------------------------------------------------------------------------------------------+ +| Name | Default | Description | ++============================+==========+=========================================================================================================+ +| ``do_read_ozone`` | False | Read ozone from a NetCDF file? NB this is the only way to apply ozone in RRTM | ++----------------------------+----------+---------------------------------------------------------------------------------------------------------+ +| ``ozone_file`` | 'ozone' | File name for ozone input file to read (assumed to be the same as the ozone variable name in NetCDF) | ++----------------------------+----------+---------------------------------------------------------------------------------------------------------+ +| ``input_o3_file_is_mmr`` | True | Does the ozone input file contain values as a mass mixing ratio (True) or volume mixing ratio (False)? | ++----------------------------+----------+---------------------------------------------------------------------------------------------------------+ +| ``co2ppmv`` | 300 | CO2 concentration in ppmv | ++----------------------------+----------+---------------------------------------------------------------------------------------------------------+ +| ``do_read_co2`` | False | Read CO2 concentraton from a NetCDF file? | ++----------------------------+----------+---------------------------------------------------------------------------------------------------------+ +| ``co2_file`` | 'co2' | File name for CO2 input file to read | ++----------------------------+----------+---------------------------------------------------------------------------------------------------------+ +| ``co2_variable_name``. | 'co2' | Variable name in CO2 input file | ++----------------------------+----------+---------------------------------------------------------------------------------------------------------+ + + +As a default, RRTM will use the atmospheric specific humidity to calculate radiative fluxes, and it needs to convert this to a volume mixing ratio. Water vapor can also be prescribed from a file or with a constant value: + ++----------------------------+----------+---------------------------------------------------------------------------------------------------------+ +| Name | Default | Description | ++============================+==========+=========================================================================================================+ +| ``convert_sphum_to_vmr`` | True | Convert specific humidity to volume mixing ratio | ++----------------------------+----------+---------------------------------------------------------------------------------------------------------+ +| ``do_read_h2o`` | False | Read water vapor from an NetCDF file? | ++----------------------------+----------+---------------------------------------------------------------------------------------------------------+ +| ``h2o_file`` | 'h2o' | Filename to read water vapor from (assumed to be the same as the h2o variable name in the NetCDF) | ++----------------------------+----------+---------------------------------------------------------------------------------------------------------+ +| ``do_fixed_water`` | False | Feed a fixed value for water vapor to RRTM? | ++----------------------------+----------+---------------------------------------------------------------------------------------------------------+ +| ``fixed_water`` | 2.e-6 | Fixed value to use if ``do_fixed_water`` is True | ++----------------------------+----------+---------------------------------------------------------------------------------------------------------+ +| ``fixed_water_pres`` | 10000 | Apply this fixed value above which pressure level? (hPa) | ++----------------------------+----------+---------------------------------------------------------------------------------------------------------+ +| ``fixed_water_lat`` | 90 | Apply this fixed value equatorward of which latitude? | ++----------------------------+----------+---------------------------------------------------------------------------------------------------------+ + + +Values of secondary gases can also be prescribed: + ++----------------------------+----------+---------------------------------------------------------------------------------------------------------+ +| Name | Default | Description | ++============================+==========+=========================================================================================================+ +| ``include_secondary_gases``| False | Use non-zero values for the following secondary gases | ++----------------------------+----------+---------------------------------------------------------------------------------------------------------+ +| ``ch4_val`` | 0 | CH4 (Methane) | ++----------------------------+----------+---------------------------------------------------------------------------------------------------------+ +| ``n2o_val`` | 0 | N2O (Nitrous Oxide) | ++----------------------------+----------+---------------------------------------------------------------------------------------------------------+ +| ``o2_val`` | 0 | O2 (Oxygen) | ++----------------------------+----------+---------------------------------------------------------------------------------------------------------+ +| ``cfc11_val`` | 0 | CFC11 (Trichlorofluoromethane) | ++----------------------------+----------+---------------------------------------------------------------------------------------------------------+ +| ``cfc12_val`` | 0 | CFC12 (Dichlorodifluoromethane) | ++----------------------------+----------+---------------------------------------------------------------------------------------------------------+ +| ``cfc22_val`` | 0 | CFC22 (Chlorodifluoromethane) | ++----------------------------+----------+---------------------------------------------------------------------------------------------------------+ +| ``ccl4_val`` | 0 | CCl4 (Carbon tetrachloride) | ++----------------------------+----------+---------------------------------------------------------------------------------------------------------+ + + + +Diagnostics +----------- +.. What diagnostics are available for this part of the code. + +Diagnostics from RRTM are under module name ``rrtm_radiation``. The outputs include the temperature tendencies due to LW/SW radiation, LW/SW radiation fluxes at the surface and the top of the atmosphere (TOA). + ++--------------------------+-----------------------------------------------------+---------------------+--------------------------------+ +| Name | Description | Units | Dimension (not including time) | ++==========================+=====================================================+=====================+================================+ +|``tdt_lw`` | RRTM temperature tendency due to LW radiation | Ks :math:`^{-1}` | (pfull, lat, lon) | ++--------------------------+-----------------------------------------------------+---------------------+--------------------------------+ +|``tdt_sw`` | RRTM temperature tendency due to SW radiation | Ks :math:`^{-1}` | (pfull, lat, lon) | ++--------------------------+-----------------------------------------------------+---------------------+--------------------------------+ +|``tdt_rad`` | RRTM temperature tendency due to radiation | Ks :math:`^{-1}` | (pfull, lat, lon) | ++--------------------------+-----------------------------------------------------+---------------------+--------------------------------+ +|``flux_lw`` | RRTM net LW surface flux (positive up) | Wm :math:`^{-2}` | (lat, lon) | ++--------------------------+-----------------------------------------------------+---------------------+--------------------------------+ +|``flux_sw`` | RRTM net SW surface flux (positive up) | Wm :math:`^{-2}` | (lat, lon) | ++--------------------------+-----------------------------------------------------+---------------------+--------------------------------+ +|``olr`` | RRTM TOA LW flux (positive up) | Wm :math:`^{-2}` | (lat, lon) | ++--------------------------+-----------------------------------------------------+---------------------+--------------------------------+ +|``toa_sw`` | RRTM net TOA SW flux (positive down) | Wm :math:`^{-2}` | (lat, lon) | ++--------------------------+-----------------------------------------------------+---------------------+--------------------------------+ +|``coszen`` | RRTM cosine (zenith_angle) | None | (lat, lon) | ++--------------------------+-----------------------------------------------------+---------------------+--------------------------------+ +|``co2`` | RRTM CO2 concentration (mass mixing ratio) | kg kg :math:`^{-1}` | (pfull, lat, lon) | ++--------------------------+-----------------------------------------------------+---------------------+--------------------------------+ +|``ozone`` | RRTM ozone concentration (mass mixing ratio) | kg kg :math:`^{-1}` | (pfull, lat, lon) | ++--------------------------+-----------------------------------------------------+---------------------+--------------------------------+ +|``rrtm_albedo`` | RRTM ozone concentration (mass mixing ratio) | None | (lat, lon) | ++--------------------------+-----------------------------------------------------+---------------------+--------------------------------+ +|``fracday`` | Daylight fraction of time interval | None | (lat, lon) | ++--------------------------+-----------------------------------------------------+---------------------+--------------------------------+ +|``t_half_rrtm`` | Half level temperatures used by RRTM | K | (phalf, lat, lon) | ++--------------------------+-----------------------------------------------------+---------------------+--------------------------------+ +|``t_full_rrtm`` | Full level temperatures used by RRTM | K | (pfull, lat, lon) | ++--------------------------+-----------------------------------------------------+---------------------+--------------------------------+ + + + +Relevant modules and subroutines +-------------------------------- +.. List the names of relevant modules, subroutines, functions, etc. +.. You can add also code snippets, using Sphinx code formatting + +The RRTM radiation scheme is initialized and called by ``src/atmos_spectral/driver/solo/idealized_moist_phys.F90``. + +Other radiation schemes employed in Isca can be found at: + +* RRTM: see ``src/atmos_param/socrates`` +* Two-stream gray radiation: see ``src/atmos_param/two_stream_gray_rad`` + + +References +---------- +.. + Add relevant references. This is done in 2 steps: + 1. Add the reference itself to docs/source/references.rst + 2. Insert the citation key here, e.g. [Vallis2017]_ + + See the Contributing guide for more info. + +[CloughEtAl2005]_ +[MlawerEtAl1997]_ +[VallisEtAl2018]_ + +Authors +------- +This documentation was written by Ruth Geen, peer reviewed by Neil Lewis, and quality controlled by Matthew Henry diff --git a/docs/source/references.rst b/docs/source/references.rst index 4248978e7..7bbeebd39 100644 --- a/docs/source/references.rst +++ b/docs/source/references.rst @@ -30,6 +30,12 @@ References **112(473)**, 693--709, doi: `10.1002/qj.49711247308 `_. +.. [CloughEtAl2005] Clough, S. and Shephard, M. and Mlawer, E. and Delamere, J. and Iacono, M. and Cady-Pereira, K. and Boukabara, S. and and Brown, P., 2005: + Atmospheric radiative transfer modeling: a summary of the AER codes. + *Journal of Quantitative Spectroscopy and Radiative Transfer*, + **91**, 233--244, + doi: `0.1016/j.jqsrt.2004.05.058 `_. + .. [YanoPlant2016] Yano, J. and Plant, R., 2016: Generalized convective quasi-equilibrium principle. *Dynamics of Atmospheres and Oceans*, @@ -47,6 +53,13 @@ References SOCRATES (Suite Of Community RAdiative Transfer codes based on Edwards and Slingo) Technical Guide. Met Office, UK. Aavailable at: https://code.metoffice.gov.uk/trac/socrates. +.. [MlawerEtAl1997] Mlawer, E. J. and Taubman, S. J. and Brown, P. D. and Iacono, M. J. and & Clough, S. A., 1997: + Radiative transfer for inhomogeneous atmospheres: RRTM, a validated correlated-k model for the longwave. + *Journal of Geophysical Research*, + **102(D14)** 16663--16682, + doi: `10.1029/97JD00237 `_. + .. [Thomson_and_Vallis2019] Thomson, S. I. and Vallis, G. K., 2019. Hierarchical Modeling of Solar System Planets with Isca. *Atmosphere*, **10 (12)**, 803, doi: `10.3390/atmos10120803 `_. +