CLBLM

---

Contents

1. Introduction
2. Cloning the Latest Release
3. General LNFL/CLBLM File Information
   1. Platforms on which CLBLM can be run
   2. Issues relating to unformatted files on UNIX and LINUX systems
   3. LNFL/CLBLM Naming Convention
4. Instructions and Tips for Running LNFL
   1. Input files for LNFL
   2. Output files for LNFL
   3. Sequence for running LNFL
5. Instructions and Tips for Compiling and Running CLBLM
   1. Required input files for CLBLM
   2. Layer numbering scheme
   3. Output files for CLBLM
   4. Sequence for running CLBLM
6. Tests
7. Frequently Asked Questions

Introduction

CLBLM (Community Line-By-Line radiative transfer Model) is an accurate and efficient line-by-line radiative transfer model derived from the Line-By-Line Radiation Transfer Model (LBLRTM). CLBLM is a modernized version of LBLRTM, written in Fortran 90 and utilizing netCDF for input and output files.

The HITRAN database provides the basis for the line parameters used in CLBLM. These line parameters, as well as additional line parameters from other sources, are extracted for use in CLBLM by a line file creation program called LNFL. A line parameter database built from HITRAN and suitable for use with LNFL can be downloaded with the AER Line File retrieval code or directory from the Zenodo repository.

CLBLM uses the line parameters and MT_CKD continuum in its calculations. The models and data are thus linked. For the latest release, the relationships are:

CLBLM Release	MT_CKD Release	Line File
v1.2	4.2	v3.8.1

If any build or run issues occur, please create an issue or contact the AER-RC Group.

For more, please see the Wiki page

Cloning the Latest Release

Assuming the output directory should be CLBLM and that the user has created an SSH key (we use RSA):

git clone --recursive [email protected]:AER-RC/CLBLM.git

Alternatively, users that have not setup an SSH key but have created a personal access token can use the HTTPS protocol:

git clone --recursive https://github.com/AER-RC/CLBLM.git

--recursive is important, because this repository is linked with our common FORTRAN modules repository that are required in the model builds. The cross section database is also added as a submodule (it is not required for all model runs). If this keyword is forgotten, one can do:

git submodule init
git submodule update

in the CLBLM directory.

The current release is CLBLM v1.2, and it is recommended that this be the version that users clone and checkout (rather than the master branch). To do this, one needs to simply checkout the v1.2 tag:

git checkout tags/v1.2

Instead of cloning, users can also download a CLBLM tarball and unpack it:

tar xvf clblm_v1.tar.gz

General LNFL/CLBLM File Information

Platforms on which CLBLM can be run

It is recommended that LNFL and CLBLM be compiled in Fortran 90. CLBLM has previously been run on Centos platforms.

Issues relating to unformatted files on UNIX and LINUX systems

Unformatted files are often not compatible between systems due to differences in the way the bytes are written to the files (big-endian versus little-endian). Note that the byteswap option available with most compilers will not work with most CLBLM unformatted output files because of the mixing of real and integer data within records.

LNFL/CLBLM Naming Convention

Specific information on the input/output files from LNFL and CLBLM is located in their respective instruction manuals, lnfl_instructions and the CLBLM User Guide, and the examples provided in the example tar files.

Instructions and Tips for Running LNFL

LNFL is used to generate a unformatted file (TAPE3) of all the line parameters required by CLBLM.

Input files for LNFL

1. TAPE1: The line parameter database in ASCII format (downloaded with the AER Line File repository or from Zenodo).

2. TAPE5: LNFL input file. The TAPE5 input file is read as formatted FORTRAN. As a consequence of the formatted read, any blank space will be read as "zero". Thus, one may leave blanks for most of the parameters and within the code they will default to an acceptable value. Real numbers format input as either E or F format, with the entire number within the range specified in the input instructions. Integers are read in with the I format and must be specified exactly in the integer format.

Output files for LNFL

1. TAPE3: Unformatted LNFL output file containing the line parameters for LBLRTM.
2. TAPE6: Informational output file.
3. TAPE7: Optional output file containing ASCII version of the parameters contained in TAPE3.

Sequence for running LNFL

• Clone the latest LNFL code and download the latest line parameter database with the AER Line File repository or from Zenodo.
• Compile LNFL using the makefiles found in the LNFL tar file. Note: one needs to compile in the build directory.
• Link the line parameter database to TAPE1 in the LNFL working directory.
• Remove TAPE3 file from the LNFL working directory.
• Edit necessary parameters in the TAPE5 input file. Note that the beginning and ending wavenumber (v₁, v₂) in TAPE5 must extend at least 25 cm^-1 beyond each end of the desired spectral range for the LBLRTM calculations.
• Run the LNFL executable.

Instructions and Tips for Compiling and Running CLBLM

CLBLM is used to generate line-by-line upwelling and downwelling transmittances, radiances, fluxes and Jacobians.

Required input files for CLBLM

1. scenes.nc: NetCDF file containing profile information (ex. temperature, pressure, molecular amounts, etc.) required to run CLBLM.

In scenes.nc, cross-sectional (XS) molecules are treated the same as every other molecule (unlike LBLRM which specifies XS molecules separately). In scenes.nc, the "molecules" attribute lists all molecules (regular and XS) in the scene, and the numMol dimension gives the total number of molecules (regular and XS). The variable molDensities [numMol, numPrflLev] then gives the molecular concentration on levels for all molecules.

2. clblm_config.json: JSON control file with model run parameters (ex. requested output, spectral inverval, instrument functions, etc.)

CLBLM does not limit the spectral interval, unlike LBLRTM, where runs must not exceed 2000 cm^-1).

Other input files are required if you are using the solar source function, cross sections, surface emissivity and reflectivity. See the CLBLM instruction manual and examples provided.

Layer numbering scheme

The CLBLM convention is that layer 1 is at the highest pressure level (lowest altitude). The layer information for a given run may be found in the scenes.nc input file.

Output files for CLBLM

The CLBLM output is a netCDF file containing the desired output (ex. transmittances/radiances).

The file specifies the dimensions of the output as the number of points in the model run (numPoints) and for some runs, the number of vertical layers (numLayers). The global attributes include the (spectralDataType) such as "monochromatic" or "convolved", the starting and ending points of the model run (v₁ and v₂), and the spectral spacing of the points (dv).

Sequence for running CLBLM

• Clone the latest CLBLM code and download the latest line parameter database with the AER Line File repository or from Zenodo.
• Compile CLBLM, scene_writer, and build_solar with the makefile in the CLBLM tar file. CLBLM has successufylly been compiled and run with gfortran 4.8.5 and netCF 4.3.3.1
• Set the environment variable CL to gfortran before compiling.

make all

• Link the line parameter database (TAPE3 from LNFL) to CLBLM/clblm_data/spectroscopy/TAPE3.
• Build the profile input file (scenes.nc). This can be done in one of two ways. Either by creating your own netcdf with profile inputs or building a netcdf from an existing LBLRTM TAPE5. For the latter, the scene_writer executable will convert an LBLRTM TAPE5 into netcdf format for use by CLBLM. In the example below, sceen_writer is executed (the first argument is the TAPE5 to convert, second argument specifies the output destination).

scene_writer TAPE5_user_defined_upwelling  user_archive/scene_files/scenes.nc

• Edit the JSON control file (clblm_config.json) to set all the configuration options (similar to LBLRTM TAPE5 parameters) for the model run.
• Run the CLBLM executable.

clblm

Tests

A run example package is provided separately from the code repository. It can be used to validate building and running of the model for select atmospheric specifications and model configurations. See README.setup in top level of the package for further direction. The CLBLM release package contains five example runs, chosen to represent the utility of CLBLM to calculate different outputs across the spectral range. The included python script can be used to run the example package. The example runs include the following:

1. Infrared monochromatic downwelling radiance (AERI case)
2. Infrared convolved (with ILS) upwelling radiance (IASI case)
3. Solar radiance with NRL 3-component solar variability (Solar case)
4. Water vapor Jacobian (Jacobian case)
5. Longwave radiative fluxes and heating rates from 10-2000 cm^-1 with Lambertian emissivity=1 (LW_Flux case)

Frequently Asked Questions

1. What is the difference between a line-by-line calculation and a band-model calculation?

Absorption/emission spectra are comprised of a complicated array of spectral lines. The HITRAN 2008 Database (Version 13.0) contains over 2,713,000 lines for 39 different molecules. In order to resolve these individual lines, a nominal spectral sampling rate of less than the mean line half width must be utilized. Such highly resolved radiative transfer calculations are called line-by-line (LBL) calculations. The computational time associated with calculating broadband fluxes from LBL calculations is formidable. A band model aims to simplify radiative transfer calculations by using approximations to represent the line-by-line characteristics of a particular spectral interval. Band models are appropriate for situations where the desired spectral resolution is much smaller than the Lorentz and Doppler widths of the spectral lines. Such approximations are also of use in general circulation models.

2. What are the standard units used in CLBLM calculations?

Output Variable	Units
Wavenumber	cm-1
Radiance	W cm-2 sr-1 / cm-1
Brightness Temperature	K
Analytic Jacobians (dR/dx)	molecules: W cm-2 sr-1 / cm-1 / log(VMR) temperature: W cm-2 sr-1 / cm-1 / K

3. Radiance Derivatives (Jacobians)

CLBLM features a straighforward setup for Jacobians, in which Jacobians can be output directly from a single CLBLM run. In the clblm_config.json input file, set clblm_out to jacobians and specify which jacobians you want to run. For example,

"clblm-out":               {"convolved jacobians":"clblm_out/jacobian.nc","jacobian-list": ["T","H2O","Tskin","emis"]}

See the CLBLM example package and instructions for more details.

4. Is it possible to scale the profile of one or more species?

Yes. Sceen_writer is able to handle the scaling provided in the LBLRTM TAPE5.

5. Does CLBLM include heavy molecule parameters (cross-sectional species)?

Heavy molecules (such as CCL4, F11, and others) can be included in CLBLM calculations. Sceen_writer handles in the inclusion of cross-section molecules included in the LBLRTM TAPE5. An additional file (FSCDXS) and directory (xs) are required for these calculations and can be obtained from the cross sections repository (which is cloned with LBLRTM if the directions in the [Cloning][#cloning] section are followed) or from the CLBLM example tar file (available in the CLBLM v1 Release).

6. Format of external surface emissivity/reflectivity files

Sea surface spectral emissivity and reflectivity files are provided with the example (available in the CLBLM v1 Release). The files must have the file names of EMISSIVITY and REFLECTIVITY. The format is as follows:

Parameter	Format	Description
V1EMIS	E10.3	Initial emissivity/reflectivity frequency value [cm-1]
V2EMIS	E10.3	Finial emissivity/reflectivity frequency value [cm-1]
DVEMIS	E10.3	Frequency Increment [cm-1]
NLIMEM	I5	Number of spectral emissivity/reflectivity points in the file
ZEMIS	E15.7	Emissivity at each spectral point

NOTE: It is assumed that the spectral emissivity/reflectivity points are equally spaced and there is a maximum number of points (see LBLRTM instructions).

7. Absorption due to clouds/aerosols

Absorption due to clouds and aerosols is not available with the initial release of CLBLM.

8. Solar Radiance

The CLBLM package contains two solar irradiance datasets; an average solar irradiance file with no temporal variability and a multicomponent solar irradiance file that allows the user to account for variability in the 11-year solar cycle, facular brighening and sunspot darkening. The solar irradiance data is derived from the NRLSSI2 model and covers a wavenumber range of 100-860000. These datasets must be downloaded from Zenodo (https://zenodo.org/records/10084886). Parameters for solar radiance calculations are set in the clblm_config.json file. For example,

"solar-irradiance":           {"option": 2, "cycle-frac" :0.382576, "facula-var": 1.0, "spot-var": 1.0}

Solar radiance runs with CLBLM require a solar source function file named SOLAR.RAD.nc. The user will generate SOLAR.RAD.nc using the build_solar executable to extract solar irradiance data from one of the above datasets. The solar configuration options (i.e. solar irradiance dataset, start/end wavenumber) for build_solar are specified in the solar_config.json. For example,

"inputs":                     [{"path": "/clblm_data/solar_irradiance/build_comb_solar_rad_multi_comp_50000plus.nc",
                                "start-wavenumber":22000.0,
                                "end-wavenumber":24000.0}],

Then build_solar is executed to build the solar source function file (SOLAR.RAD.nc).

build_solar solar_config.json

See the CLBLM example package and instructions for more details.

9. Line coupling/mixing

Line coupling parameters are utilized in LBLRTM for O₂, CO₂ and CH₄. The line coupling parameters are provided in the AER line parameter database (available in the AER Line File repository or on Zenodo) and are written to the line parameter input file (TAPE3) by LNFL.

10. What is the appropriate reference for CLBLM calculations in journal articles and presentations?

11. How do you calculate fluxes?

CLBLM features built-in flux calculations, such that radiative fluxes and heating rates can be output directly from a single CLBLM run. In the clblm_config.json input file, add the flux-flags group and specify the flux parameters, such as the spectral interval for the flux output and the number of quadrature angles to use for the flux calculation. For example,

"flux-flags":                  {"flux_flag":true, "dv_flux":10.0,"nang":3}

See the CLBLM example package and instructions for more details.