Software for the Correlated K-Distribution Model Intercomparison Project (CKDMIP) Contact: Robin Hogan, ECMWF <r.j.hogan@ecmwf.int> 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.