Software for the Correlated K-Distribution Model Intercomparison
Project (CKDMIP)

Contact: Robin Hogan, ECMWF <[email protected]>
Project home page: https://confluence.ecmwf.int/display/CKDMIP/
Last update of this file: 1 June 2021

INTRODUCTION

This package contains software to perform radiative transfer
calculations both on absorption spectra produced by LBLRTM, and on
optical depths produced by CKD models. It also provides some Matlab
software to compare the accuracy of CKD models to the reference
line-by-line calculations, and the LaTeX source code of the CKDMIP
documentation.

For a scientific introduction to CKDMIP, see the protocol paper
on the CKDMIP home page (link above) and the CKDMIP documentation in
the "doc" directory.

BUILD

The software is in Fortran and has been tested on a Linux system using
the gfortran compiler. It requires the NetCDF library, version 4.x,
i.e. providing support for NetCDF4/HDF5 files.  If you have all these
then try simply running "make" in the top-level directory, which
should compile the source code in the "src" directory and produce two
executables in the "bin" directory.  If the build fails then try to
edit src/Makefile, in particular to use your prefered Fortran
compiler, or to set the NETCDF_INCLUDE and NETCDF_LIB variables to
use the NetCDF4 library if it is not in a standard location.

CONVERTING RAW LBLRTM FILES TO NETCDF4/HDF5

The "lblrtm2nc" executable in the "bin" directory converts the raw
binary output from LBLRTM into a NetCDF4/HDF5 file. This was used to
generate the absorption spectra released as part of CKDMIP, but it is
not expected that CKDMIP participants will use it unless they are
working with LBLRTM themselves. The "work/lblrtm2nc" directory
contains the scripts that were used to generate the three CKDMIP
datasets "evaluation1", "mmm" and "idealized".  Note that LBLRTM
produces one file per profile, layer and spectral block (and there
were 4 blocks to cover the full longwave spectrum and 27 to cover the
full shortwave spectrum).  The "make_lblrtm_links_*" scripts in this
directory make symbolic links with a file name conforming to that
expected by lblrtm2nc.

PERFORMING RADIATIVE TRANSFER CALCULATIONS

The "ckdmip_lw" executable in the "bin" directory performs longwave
radiative transfer calculations, "ckdmip_sw" performs shortwave
calculations and "ckdmip_tool" is a general utility with multiple
functions as described in the documentation
(doc/ckdmip_documentation.tex). Taking ckdmip_lw as an example, it can
be run in two configurations:

1. To produce line-by-line benchmarks it is run on the spectral
optical depth profiles for a number of individual gases, which are
contained in the files provided as part of CKDMIP. Since the molar
absorptions of all gases except water vapour are very close to being
independent of concentration, the optical depths of some gases may be
scaled when they are read in by ckdmip_lw in order to represent
different climate scenarios.

2. To produce equivalent flux profiles by a CKD model but using the
same radiative transfer algorithm, ckdmip_lw can take as input a
NetCDF file containing three variables: the pressure at half levels
(layer interfaces), the optical depth of full levels (layers) in a
number of g-points, and the Planck function at half levels (layer
interfaces) integrated over the parts of the spectrum that correspond
to those g-points.  The ckdmip_lw program will then compute fluxes for
each g-point and sum across g-points to obtain the upwelling and
downwelling broadband flux profiles.

PLEASE NOTE: when run in configuration 1 above, ckdmip_lw is SLOW.
This is because of the time to load the optical depths from file into
memory.  You will need a workstation with a significant amount of
memory (32 GB is recommended) and the CKDMIP optical depth files
should be stored on a local disk, rather than read across a network.

For further details of how to use ckdmip_lw, look at the documentation
in the "doc" directory.

The "work/lw" directory contains several scripts that run
ckdmip_lw:

run_lw_lbl_evaluation.sh - this runs ckdmip_lw on the line-by-line
optical depth files for the nine gases (H2O, O3, N2, O2, CO2, CH4,
N2O, CFC11, CFC12) of the "evaluation1" dataset, with different
scalings of the last five gases, to produce benchmarks for (1) the
four scenarios "present", "preindustrial", "future" and "glacialmax"
described in the protocol paper, and (2) present-day conditions but
with one of the last five gases perturbed over a suitable range in
order to test the ability of CKD models to simulate the radiative
forcing of changes to a single gas.  Creation of the full set of
scenarios typically takes 24-48 hours on a good workstation.

run_lw_ckd_evaluation.sh - for the same scenarios, this runs ckdmip_lw
on files generated by a CKD model containing the Planck function and
optical depth in each of a number of g-points.

test_merge_only.sh - ckdmip_lw can also simply merge the optical
depths from a combination of gases, which can be useful if a CKD model
intends to use a "hybrid" or "composite" gas to represent multiple
gases in present-day concentrations. This script demonstrates this
feature of ckdmip_lw.

DOCUMENTATION

If you have LaTeX on your system then type "make" in the "doc"
directory to create the "ckdmip_documentation.pdf" file, which
describes both the CKDMIP datasets and how to use the ckdmip_lw
program.

MATLAB SCRIPTS

Two scripts are provided in the "work/matlab" directory to evaluate a CKD
model against line-by-line reference calculations.

evaluate_ckd_fluxes.m - this script compares a CKD model against the
line-by-line reference calculations for the 50 profiles of the
"evaluation1" dataset, comparing TOA upwelling fluxes, surface
downwelling fluxes, and heating-rate profiles (all broadband), for the
four CKDMIP scenarios of "present", "preindustrial", "future" and
"glacialmax".

evaluate_ckd_forcing.m - this script evaluates a CKD model in terms of
the change to net TOA and surface fluxes, compared to present day,
from perturbing CO2, CH4, N2O, CFC11 and CFC12 over the range
suggested in the CKDMIP protocol paper.

Sorry these scripts are not in Python.

LICENSE 

All the software in this package is released under the Apache License,
version 2, provided in the LICENSE file.