Table of Contents

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.

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:

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

mc_backward

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

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:

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

pseudospherical

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

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

mc_polarisation

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

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

mc_vroom

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

mc_delta_scaling

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

mc_vroom

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