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.

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:

First you need to think about the spectral range and spectral resolution required for your calculation. As long as you stay in the ultraviolet or the lower visible spectral range you don't need to consider anything. 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 section). For most applications you need to select a correlated k-distribution, e.g. correlated_k lowtran 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 transmittance_wl_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. correlated_k kato2 or correlated_k 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 correlated_k options.

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).

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.

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.

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. ozone_column which modifies the ozone column, or co2_mixing_ratio, …

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.

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.

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.

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 disort2 which is the method of choice for most applications. There are other solvers like rte_solver twostr (faster but less accurate), rte_solver polradtran (polarization-dependent solver), or rte_solver sdisort (pseudo-spherical).

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 sum or correlated_k lowtran and output integrate. Check also other options like filter_function_file, brightness, etc. Instead of calibrated spectral quantities you might also want transmittance or reflectivity.

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!

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.