source: trunk/LMDZ.GENERIC/DOC/kspectrum.tex @ 3556

\chapter{Changing the radiative transfer properties}

\label{sc:kspectrum}

One of the key advantages of the LMD generic model is the ability
to work with arbitrary gas and aerosol mixtures in the radiative transfer.
In this chapter we describe how to produce new correlated-k absorption coefficients
and implement them in the GCM.

\section{Producing the high-resolution data}
We use the open-source software {\tt kspectrum} to produce line-by-line (LBL) absorption coefficients. {\tt Kspectrum}
is freely available online at

\begin{verbatim}
http://code.google.com/p/kspectrum/
\end{verbatim}

See its user manual for general information on installation and basic usage.

To produce LBL data on a grid of pressure and temperature suitable for the GCM, the program \verb+make_composition.F90+ is used (available in the {\tt utilities} folder of the main GCM directory). This may be compiled with the script {\tt compile} in the same folder. Once this has been done, the two scripts \verb+prekspectrum+ and \verb+postkspectrum+ are used to feed {\tt kspectrum} the correct inputs and convert the LBL data to correlated-k coefficients afterward. These scripts require three environment variables to be defined: {\tt DWORK\_DIR}, {\tt KSPEC\_DIR} and {\tt BANDS\_DIR}.

In the following example, we create a database with a mixed CO$_2$ / H$_2$O atmosphere where CO$_2$ is the dominant gas. First, the three environment variables are set as

\begin{verbatim}
DWORK_DIR=/san/home/rdword/corrk_data/CO2_H2Ovar
KSPEC_DIR=/san/home/rdword/kspectrum/kspec_1
BANDS_DIR=32x36
\end{verbatim}

We then create a directory that includes files \verb+Q.dat+, \verb+p.dat+ and \verb+T.dat+ to define the number of gaseous species and pressure and temperature gridpoints. For each file the first number gives the number of points / species.   See the folder \verb+corrk_example+ in \verb+utilities+ for the example we will describe here.

Typing {\tt prekspectrum} results in the following prompt:

\begin{verbatim}
Name of atmosphere / planet:
\end{verbatim}

The planet name is for reference only and does not affect the results. After this, the values of the temperature, pressure and variable gas (H2O) grids are displayed, and you are asked for the CO2 mixing ratio:

\begin{verbatim}
 Correlated-k temperature grid:
 1.  100.0 K
 2.  150.0 K
 3.  200.0 K
 4.  250.0 K
 5.  300.0 K
 6.  350.0 K
 7.  400.0 K

 Correlated-k pressure grid (mBar):
 1. 1 x 10 ^-3 mBar
 2. 1 x 10 ^-2 mBar
 3. 1 x 10 ^-1 mBar
 4. 1 x 10 ^ 0 mBar
 5. 1 x 10 ^ 1 mBar
 6. 1 x 10 ^ 2 mBar
 7. 1 x 10 ^ 3 mBar
 8. 1 x 10 ^ 4 mBar
 9. 1 x 10 ^ 5 mBar

 nmolec=           2
 Temperature layers:             7
 Pressure layers:                9
 Mixing ratio layers:            7
 Total:                        441

 Please enter vmr of CO2
\end{verbatim}

We chose {\tt 1.0} as there are no other gases (the mixing ratio is automatically changed to take into account the variable gas). After {\tt prekspectrum} exits, we can view the resulting \verb+composition.in+ file stored in the \verb+data/+ directory of \verb+kspectrum+:

\begin{verbatim}
Atmospheric composition input data file for planet: Zarmina
Number of atmospheric levels: 441
Number of molecules:   2

       z (km)     /    P (atm)     /  T (K)   /  x[CO2]    /  x[H2O]
  0.000000000E+00  0.986923267E-06  0.100E+03  0.99999E+00  0.10000E-06
  0.000000000E+00  0.986923267E-06  0.150E+03  0.99999E+00  0.10000E-06
  0.000000000E+00  0.986923267E-06  0.200E+03  0.99999E+00  0.10000E-06
  ...
\end{verbatim}

Typing \verb+run_kspectrum+ in the \verb+kspectrum+ directory then submits the process as a batch job. Beware: calculating LBL coefficients for multiple gases and several hundred $p$, $T$ values can take several weeks at current processing speeds!

\section{Performing the correlated-k conversion}

Once the LBL data is calculated, it's time to convert it to correlated-k format. We do this using a program \verb+generate_kmatrix.F90+ which is also stored in the \verb+utilities+ folder and is called by \verb+postkspectrum+. In addition to the data generated by \verb+kspectrum+ and the original \verb+.dat+ files, it requires definition of the spectral bands to be used in the GCM. In this example we use a folder \verb+32x36+, containing files \verb+narrowbands_VI.in+ and \verb+narrowbands_IR.in+. These files define the number and widths all all bands in the visible and infrared, respectively. They can of course be modified depending on blackbody temperatures and the tradeoff required between model speed and accuracy - the 
 examples given provide accurate results for planets around Sun-like or M-class stars with surface temperatures in the 200-350 K range. {\tt postkspectrum} moves the LBL database to the {\tt DWORK\_DIR} directory along with the script {\tt run\_kmatrix}. When {\tt run\_kmatrix} is submitted in batch mode, it calls \verb+generate_kmatrix.exe+ automatically for both the visible and the infrared. 
Correlated-k conversion is much quicker than the LBL calculation - for this database on current (2011) systems it should take only a few hours.

\section{Implementing the absorption data in the GCM}

To use our new correlated-k coefficients, we symbolically link the correlated-k folder to the {\tt datagcm} directory defined in the GCM file \verb+phystd/datafile.h+ (it's best to avoid copying the data directly due to space considerations). All that is left is to change {\tt corrkdir} in \verb+callphys.def+ to the correct name (\verb+CO2_H2Ovar+ in this example). Provided that we compile the GCM with the correct number of bands, e.g.

\begin{verbatim}
makegcm -d 32x32x20 -t 1 -b 32x36 -p std gcm
\end{verbatim}

it will run automatically with the new radiative transfer. The GCM checks the radiative transfer data on initialization vs. the values given in 
\verb+gases.def+, to verify that thermodynamic values (e.g. $\mu_{gas}$, $c_p$) match the correlated-k data in the model.