basic_usage

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
===== 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
[[http://www.libradtran.org/doku.php?id=documentation|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<html>&mu;</html>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<html>&deg;</html> 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<html>&mu;</html>m between 1 and 2km, and an optical thickness of
around 15; the second is an ice cloud with effective particle radius
20<html>&mu;</html>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
[[http://www.meteo.physik.uni-muenchen.de/dokuwiki/doku.php?id=lsmayer:monte_carlo_modell_mystic|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<html>&plusmn;</html>20.0 and for the diffuse downward
199.4<html>&plusmn;</html>14.6. In most cases the noise is Gaussian
which implies that 68% of the model runs lie within
<html>&plusmn;</html>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<html>&plusmn;</html>2.4 for the direct and
203.8<html>&plusmn;</html>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 <html>&plusmn;</html>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<html>&plusmn;</html>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<html>&plusmn;</html>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<html>&plusmn;</html>0.18 for the radiance. The respective disort
result is 56.53 - again both agree within <html>&plusmn;</html>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
  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<html>&plusmn;</html>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<html>&plusmn;</html>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<html>&plusmn;</html>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<html>&plusmn;</html>0.002 for the diffuse downward irradiance (disort: 1.224). Now add
  mc_polarisation
and obtain 1.234<html>&plusmn;</html>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 
  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!

=== References ===

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.