## Table of Contents## Basic UsageThose 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 ## 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 ## 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 ## 3. Geometry
Geometry includes the location of the sun which is defined with
## 4. What do you need to setup the atmosphere?
To define an atmosphere, you need at least an ## 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. ## 4b. Aerosols?
If you want aerosol, switch it on with ## 4c. Clouds?
uvspec allows water and ice clouds. Define them with 1 0.1 10
and an 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 ## 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 ## 6. Postprocessing
The spectral grid of the output is defined by the extraterrestrial
spectrum. If you want spectrally integrated results, use either
## 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 ## Play around with MYSTICThe 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 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 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 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 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 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 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! ## ReferencesMishchenko, 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. |