Basic Usage

Those users who are not familiar with the predecessor of libRadtran, uvspec, please note the following: The central program of the package is an executable called uvspec which can be found in the bin directory. If you are interested in a user-friendly program for radiative transfer calculations, uvspec is the software you want to become familiar with. A description of uvspec is provided in the first part of the manual. Examples of its use, including various input files and corresponding output files for different atmospheric conditions, are provided in the examples directory. For a quick try of uvspec go to the examples directory and run

  ../bin/uvspec < UVSPEC_CLEAR.INP > test.out

For the format of the input and output files please refer to the manual.

The bin directory also provides related utilities, like e.g. a mie program (mie), some utilities for the calculation of the position of the sun (zenith, noon, sza2time), a few tools for interpolation, convolution, and integration (spline, conv, integrate), and some other small tools.

How to setup an input file for your problem (checklist)

There are several steps to consider when setting up an input file for your specific problem. First of all we strongly recommend that you read a radiative transfer textbook to become familiar with what is required for your problem. After defining your problem you may in principle find all information for setting up the input file and understanding the contents of the output file in the manual (but who reads manuals anyway?). Below is a short checklist including the steps you need to consider for each problem:

1. Wavelength grid / band parameterization

First you need to think about the spectral range and spectral resolution required for your calculation. Per default the REPTRAN absorption parameterization is used which is available for the full spectral range from the UV to the far IR. In the ultraviolet or the lower visible spectral range molecular absorption varies smoothly with wavelength in this range and a calculation with 0.5 or 1nm step width should be sufficient. Above 500nm, however, absorption by water vapour, oxygen, and other trace gases starts; these absorption lines are very narrow, and a spectral calculation which resolves all lines is not feasible for most applications (such a line-by-line calculation is possible, however, if you provide your own spectral absorption cross sections). For most applications you have to use a parameterization for molecular absorption, for example the representative wavelengths parameterization, e.g. mol_abs_param reptran which is used by default and which allows pseudo-spectral calculations (meaning that you still can calculate radiation at any wavelength you want, but the gas absorption is provided only at limited resolution - if you select the wavelengths too close, you will see the steps in your spectrum). For a spectral or pseudo-spectral calculation, you may define your own wavelength grid with wavelength_grid_file and we recommend to do that because otherwise you get the default 1nm step which might be too expensive for your application. Finally, in order to calculate integrated shortwave or integrated longwave radiation, please choose one of the pre-defined correlated-k distributions, e.g. mol_abs_param kato2 or mol_abs_param fu because these are not only much more accurate but also much faster than a pseudo-spectral calculation. Please read the respective sections in the manual to become familiar with the mol_abs_param options.

2. Quantities

The next point one needs to consider is the desired radiation quantity. Per default, uvspec provides direct, diffuse downward and diffuse upward solar irradiance and actinic flux at the surface. Thermal quantities can be calculated with source thermal - please note that uvspec currently does either solar or thermal, but not both at the same time. If both components are needed (e.g. for calculations around 3μm) then uvspec needs to be called twice. To calculate radiances in addition to the irradiances, simply define umu, phi, and phi0 (see next section).

3. Geometry

Geometry includes the location of the sun which is defined with sza (solar zenith angle) and phi (azimuth). The azimuth is only required for radiance calculations. Please note that not only the solar zenith angle but also the sun-earth-distance change in the course of the year which may be considered with day_of_year (alternatively, latitude, longitude, and time may be used). The altitude of the location may be defined with altitude which modifies the profiles accordingly. Radiation at locations different from the surface may be calculated with “zout” which gives the sensor altitude above the ground. For satellites use “zout TOA” (top of atmosphere). For radiance calculations define the cosine of the viewing zenith angle umu and the sensor azimuth phi and don't forget to also specify the solar azimuth phi0. umu>0 means sensor looking downward (e.g. a satellite), umu<0 means looking upward. phi = phi0 indicates that the sensor looks into the direction of the sun, phi-phi0 = 180° means that the sun is in the back of the sensor.

4. What do you need to setup the atmosphere?

To define an atmosphere, you need at least an atmosphere_file which usually contains profiles of pressure, temperature, air density, and concentrations of ozone, oxygen, water vapour, carbon dioxide, and nitrogen dioxide. The set of six standard atmospheres provided with libRadtran is usually a good start: afglms (mid-latitude summer), afglmw (mid-latitude winter), afglss (sub-arctic summer), afglsw (sub-arctic winter), afglt (tropical), and afglus (US standard). If you don't define anything else, you have an atmosphere with Rayleigh scattering and molecular absorption, but neither clouds, nor aerosol.

4a. Trace gases?

Trace gases are already there, as stated above. But sometimes you might want to modify the amount. There is a variety of options to do that, e.g. mol_modify O3 which modifies the ozone column, or mixing_ratio CO2, …

4b. Aerosols?

If you want aerosol, switch it on with aerosol_default and use either the default aerosol or one of the many aerosol_ options to setup whatever you need.

4c. Clouds?

uvspec allows water and ice clouds. Define them with wc_file and ic_file and use one of the many wc_ or ic_ options to define what you need. Please note that for water and ice clouds you also have a choice of different parameterizations, e.g. ic_properties fu, yang, baum, … - these are used to translate from liquid/ice water content and droplet/particle radius to optical properties. You need some experience with clouds to define something reasonable. Here are two typical choices for a wc_file 2 0 0

 1 0.1 10  

and an ic_file

10      0  0
 9  0.015 20  

The first is a water cloud with effective droplet radius of 10μm between 1 and 2km, and an optical thickness of around 15; the second is an ice cloud with effective particle radius 20μm between 9 and 10km and an optical thickness of about 1.

4d. Surface properties?

Per default, the surface albedo is zero - the surface absorbs all radiation. Define your own monochromatic albedo or spectral albedo_file or a BRDF, e.g. for a water surface which is mainly determined by the wind speed cox_and_munk_u10.

5. Choice of the radiative transfer equation (rte) solver

The rte-solver is the engine, or heart, in any radiative transfer code. All rte-solvers involve some approximations to the radiative transfer equations, or the solution has some uncertainties due to the computational demands of the solution method. The choice of rte-solver depends on your problem. For example, if your calculations involves a low sun you should not use a plane-parallel solver, but one which somehow accounts for the spherical shape of the Earth. You may choose between many rte-solvers in uvspec. The default solution method to the radiative transfer is the discrete ordinate solver disort which is the method of choice for most applications. There are other solvers like rte_solver twostr (faster but less accurate), rte_solver mystic and mc_polarisation (polarization included), or rte_solver disort and and pseudospherical to get pseudo-spherical geometry.

6. Postprocessing

The spectral grid of the output is defined by the extraterrestrial spectrum. If you want spectrally integrated results, use either correlated_k kato2/fu and output_process sum or correlated_k lowtran and output_process integrate. Check also other options like filter_function_file, output_quantity brightness, etc. Instead of calibrated spectral quantities you might also want output_quantity transmittance or output_quantity reflectivity.

7. Check your input

Last but not least, make always sure that uvspec actually does what you want it to do! A good way to do that is to use verbose which produces a lot of output. To reduce the amount, it is a good idea to do only a monochromatic calculation. Close to the end of the verbose output you will find profiles of the optical properties (optical thickness, asymmetry parameter, single scattering albedo) which give you a pretty good idea e.g. if the clouds which you defined are already there, where the aerosol is, etc. As a general rule, never trust your input, but always check, play around, and improve. For if thou thinkest it cannot happen to me and why bother to use the verbose option, the gods shall surely punish thee for thy arrogance!

Play around with MYSTIC

The Monte Carlo code for the physically correct tracing of photons in cloudy atmospheres (MYSTIC) is fundamentally different from other solvers in the sense that it determines the result by random tracing of individual photons through the atmosphere. For a simple description of the technique see the publication by Mayer (2009) and the other papers listed here. In the following, we show how to play around and explore MYSTIC.

First, try a simple uvspec input file:

atmosphere_file ../data/atmmod/afglus.dat
source solar    ../data/solar_flux/atlas_plus_modtran

wavelength 450

In this example the default solver (disort) is used and uvspec will provide familar output like

450.000  1.670252e+03  2.048350e+02 -2.314766e-13  1.329144e+02  4.177456e+01  6.935632e-14 

If you repeat the simulation, you will get an identical result over and over again. Now let's try MYSTIC by simply adding

rte_solver mystic

to the above input and run uvspec 10 times. You might get

450.000  1.643995e+03  1.997293e+02  0.000000e+00  1.308250e+02  4.676865e+01  0.000000e+00 
450.000  1.673167e+03  1.852792e+02  0.000000e+00  1.331464e+02  3.027929e+01  0.000000e+00 
450.000  1.704421e+03  1.832073e+02  0.000000e+00  1.356335e+02  4.074436e+01  0.000000e+00 
450.000  1.712756e+03  1.977188e+02  0.000000e+00  1.362968e+02  3.850349e+01  0.000000e+00 
450.000  1.679417e+03  1.977593e+02  0.000000e+00  1.336438e+02  3.629829e+01  0.000000e+00 
450.000  1.652330e+03  1.954993e+02  0.000000e+00  1.314883e+02  3.828460e+01  0.000000e+00 
450.000  1.662748e+03  2.040408e+02  0.000000e+00  1.323173e+02  3.629640e+01  0.000000e+00 
450.000  1.675250e+03  2.247512e+02  0.000000e+00  1.333122e+02  4.490242e+01  0.000000e+00 
450.000  1.681501e+03  2.247862e+02  0.000000e+00  1.338096e+02  4.674322e+01  0.000000e+00 
450.000  1.681501e+03  1.811337e+02  0.000000e+00  1.338096e+02  3.694756e+01  0.000000e+00 

The result is close to disort, but obviously different each time you run uvspec. The difference is caused by the photon noise. You may compute the noise by calculating the standard deviation of the 10 individual results. For the direct irradiance (column 2) we obtain 1676.7±20.0 and for the diffuse downward 199.4±14.6. In most cases the noise is Gaussian which implies that 68% of the model runs lie within ±1 standard deviation and 95% within 2 standard deviations. That way you can always determine the statistical noise of your result. The noise is of course determined by the number of photons run in the simulation. Try increasing the number of photons to 100,000 (the default was 1,000 in the above example) by adding

mc_photons 100000

to the input file. Now we pbtain 1671.1±2.4 for the direct and 203.8±1.9 for the diffuse irradiance. The noise has decreased roughly by a factor of 10. In fact, the noise is proportional to 1 / sqrt (mc_photons) which means, if you want to reduce the noise by a factor of 10 you need to increase the number of photons and thus the computational time by a factor of 100. Please note that in both calculations the disort result lies within ±2 standard deviations.

Now let's try something more complicated: Calculate integrated thermal irradiance using the following input file:

atmosphere_file ../data/atmmod/afglus.dat

source thermal
mol_abs_param fu
wavelength_index 7 18
output_process sum

rte_solver mystic

mc_photons 100000

For the diffuse downward irradiance we obtain 267.7±27.6 W/m2 which is unacceptably noisy. When you read the above mentioned publications, you will find that thermal irradiance should rather be calculated in “backward” mode. Add


to the input file and repeat the calculation. You will obtain something like 283.3±0.5 W/m2. Noise and also computational time have decreased dramatically. The respective disort result is 283.6 W/m2 and the disort computational time is only a factor of 3 faster compared to MYSTIC (the latter was 0.3 s for integrated longwave irradiance). Please note that in backward mode, only one quantity is calculated at a time. The default is diffuse downward irradiance. If you need diffuse upward instead, please try

mc_backward_output eup

Now let's try radiances with the following input file:

atmosphere_file ../data/atmmod/afglus.dat
source solar  ../data/solar_flux/atlas_plus_modtran

wavelength 400 

sza 45

rte_solver mystic
mc_photons 100000
umu -1
phi 0

Here we are looking straight upward from the surface in the blue (400 nm). With the default solver disort you get the result directly to stdout while MYSTIC does not provide the radiances there. The latter are found in mc.rad.spc (see documentation). Here we obtain 56.68±0.18 for the radiance. The respective disort result is 56.53 - again both agree within ±2 standard deviations.

Now something special: Try calculating radiances for several directions by replacing the umu line with

umu -1.0 -0.9 -0.8

You will notice that MYSTIC does the calculation only for the first umu value. In contrast to disort each angle pair (umu, phi) has to be calculated separately for which reason we haven't implemented the option to calculate several angles at the same time.

So far we have only calculated things which could also have been calculated with disort - usually faster and without noise. Now let's do something which cannot be done with disort. Try the following:

atmosphere_file ../data/atmmod/afglus.dat
source solar ../data/solar_flux/atlas_plus_modtran
wavelength 400
sza 88

As you know, the plane-parallel approximation in disort is not very accurate for low sun (here: SZA 88 degrees). With the default solver we obtain 22.01 for the diffuse downward irradiance. Using the pseudospherical disort version


we obtain 34.72 instead which is considerably different. Now add the following to the input file:

rte_solver mystic
mc_spherical 1D
mc_photons 100000

in order to obtain 34.47±0.36. MYSTIC includes a fully spherical solver which is invoked with mc_spherical. Here the results of MYSTIC and disort disagree by more than 2 standard deviations. Let's repeat the experiment and increase the number of photons to 1000000 in order to obtain 34.50±0.09. The result differ in fact. Here you should better trust MYSTIC because MYSTIC is a fully spherical solver without approximations while the pseudospherical approximation is obviously an approximation. Now let's try a really spherical case: Use

sza 96 

instead of 88 degrees. 96 degrees is the onset of nautical twilight (during nautical twilight, sailors can take reliable star sightings of well-known stars). You shouldn't trust the pseudo-spherical approximation anymore for such low sun, but spherical MYSTIC provides a reliable result of 0.091±0.006 (the pseudospherical disort result was 0.058 in that case which is still the correct order of magnitude, but we know that the pseudospherical approximation may provide complete nonsense for such SZAs for certain circumstances).

Using spherical MYSTIC you may safely compute radiances and irradiances for any SZA between 0 and 180 degrees. Also, radiances for low viewing angles are correctly computed while those are not handled correctly with the plane-parallel or pseudo-spherical approximationss. Please note that spherical MYSTIC automatically activates backward mode. If you need quantities other than diffuse downward irradiance please use mc_backward_output …

MYSTIC also includes a fully vectorized (polarization-dependent) solver. Try

atmosphere_file ../data/atmmod/afglus.dat
source solar ../data/solar_flux/atlas_plus_modtran

wavelength 300

sza 30

rte_solver mystic
mc_photons 1000000

to obtain 1.224±0.002 for the diffuse downward irradiance (disort: 1.224). Now add


and obtain 1.234±0.002 which is 1% higher. The neglect of polarization may cause errors in the radiance of up to 10% according to Mishchenko et al. (1994) while errors in the irradiance are probably much smaller, as shown in this example. However, the real virtue of the vectorized MYSTIC is the possibility to calculate the full Stokes Vector, required e.g. for a number of modern remote sensing instruments like POLDER, PARASOL, GOSAT, etc. Simply add

umu -1 
phi 0

to the above example and check mc.rad.spc:

300.00000    0    0    0 0.433473
300.00000    0    0    0 -0.0461689
300.00000    0    0    0 -0.000196948
300.00000    0    0    0 0

These are the four components of the Stokes Vector (I,Q,U,V) for the chosen wavelength and geometry.

These examples should be enough to get you started with MYSTIC. It is immediately clear that the required number of photons (and hence the computational time) depends strongly on the problem. Also, some problems are better solved in forward mode while some (e.g. thermal irradiance) should rather be done in backward mode. Strongly peaked scattering phase functions of aerosol and water clouds and in particular of ice clouds may cause spikes which can be removed by switching on


It is important to note that all these switches only affect the noise, but not the absolute value since MYSTIC is “physically correct” by definition. The only exception is


which truncates the phase function and may introduce some systematic uncertainty. It's usually not required - use


instead. If you plan to use MYSTIC for your work, make sure you get familiar with the options and check the above mentioned literature!


Mishchenko, M.I., A.A. Lacis, and L.D. Travis, 1994. Errors induced by the neglect of polarization in radiance calculations for Rayleigh-scattering atmospheres. JQSRT 51, 491-510.

basic_usage.txt · Last modified: 2017/09/13 10:37 by admin
Recent changes RSS feed Creative Commons License Valid XHTML 1.0 Valid CSS Driven by DokuWiki
Drupal Garland Theme for Dokuwiki