How to convert to the new syntax?

This is simple: We provide a Python script to translate from the old
syntax (before July 2014) to the new syntax (after July 2014):

python src_py/translate.py uvspec.inp > uvspecnew.inp

How serious are serious differences reported by "make check"?

They are usually not as serious as it sounds. We haven't had a case where libRadtran worked on one computer and produced really wrong results on another. However, radiative transfer equation solvers like disort are numerical methods which are affected by the limited numerical precions of processors, and these differ from processor to processor and sometimes even from compiler to compiler. Usually, large differences occur for small numbers. As an example, in the near-infrared the diffuse downward irradiance is very small while the direct beam source is large - hence one may expect some uncertainty in the small diffuse radiation. Citing from DISORT2.doc:

DISORT has certain intrinsic limitations because of computer precision.
These limitations are related to ordinary computer
"roundoff error" and have nothing to do with user-controllable
(through the number of streams NSTR) "truncation error". DISORT
is free of the *catastrophic* growth of roundoff error that
plagued pre-1980 discrete ordinate programs, but certain parts
of the calculation (the eigenvalue/vector and Gauss quadrature
rule computations, and to a much lesser extent the linear
equation solving computations) are just inherently more sensitive
to roundoff than the rest of DISORT, because they involve so many
arithmetic operations.
The reason DISORT.f does the eigenvalue/vector and Gauss
quadrature rule computations in double precision is that DISORT
was originally developed on 32-bit-single-precision computers
(VAXen and IBMs) which were too inaccurate for those computations.
Running DISORT.f on a typical 32-bit-single-precision computer
usually gives results precise to at least 2-3 significant digits,
although for certain special situations the precision can fall to
one significant digit. Results can even have NO significant digits
when they fall below about 10**(-8) times the driving radiation,
as one can see in the fluxes in some of the test problems.

Also, disort does e.g. not return 0 in cases where it should. E.g. the irradiance reflected by a surface of albedo 0
usually assumes a tiny value different from 0 (sometimes even negative) which of course strongly depends on numerical precision. Hence it is difficult to estimate a-priori which deviations are serious and which are not. Deviations in the order of 1% or smaller are rarely serious, while in case of much larger differences the user is recommended to compare the output against the output stored in the examples directory to see what is the case for the deviation.

My input file doesn't do what I want it to do

Try the “verbose” option!

How does DISORT work?

There are several sources that describe the inner workings of DISORT. Please check out:

Where is the tools directory?

The directory structure has changed a bit from version 1.3 to version 1.4. We made libRadtran a bit more compliant to the “standard” source code structure. All the sources are now in src, the library sources in libsrc_c and libsrc_f, and the binaries go into bin. While this is not a big improvement in itself, one may now use “make install” as with most other UNIX/Linux tools.

How to redirect uvspec output

uvspec outputs both to stdout and stderr. Sometimes it is advantageous to redirect this output to different files. Two ways of doing this on a unix type machine within the bash shell are:

(uvspec < uvspec.inp > uvspec.out) >& uvspec.err

and

uvspec < inp.inp > uvspec.out 2> uvspec.err

Choose whatever is your favorite. It is also possible to do this from within scripts. For an OS independent method implemented in python check out the uvspec graphical user interface (GUI).

uvspec on multiprocessor machines

There are two ways of utilizing the power of all processors on a multiprocessor machines for libRadtran/uvspec calculations.

Make a script the generates input files and takes care of output files. Start that script simultaneously as many times as you have processors. Make sure that all input and output files are uniquely named.

uvspec may be invoked by calling the uvspec() function from within a C-program. To avoid memory leakage use fork() to invoke uvspec. An example is provided in src/uvspecfunction.c. If you fork for e.g. 32 times, you will have 32 independent processes running. Convenient if you have a 32 processor machine.

If you have a single uvspec run that takes a long time there is no multiprocessor support other than that provided by the compiler. In such a case you may consider breaking up the input file if possible.

I have problems compiling libRadtran under Ubuntu

It appears that Ubuntu installs more than one Fortran compiler (f77 and gfortran) at the same time and the configure script may have trouble with that. A symptom for this problem is a configure log which looks as follows:

...
Fortran compiler: f77 -O
Fortran linker:
Fortran libraries:
...

The solution is simple: You need to tell configure to use gfortran and this is done e.g. by setting a variable

export F77=gfortran

before calling configure.

I have problems compiling libRadtran under Mac OS X

To be able to build the libRadtran C and Fortran libraries and associated
tools, XCODE from apple is first needed. It either is included with
your computer on a DVD or you may get it from

http://developer.apple.com/tools/xcode/

The gcc that comes with xcode will not compile libRadtran. Thus, please install
gcc and gfortran from http://www.macports.org using the port command (you have to install the port command first) in a terminal window:

sudo port install gcc

Also add the following lines to your .profile file and remember to “source .profile” afterwards.

The rest is easy. Open a terminal under Max OS X and following the
standard libRadtran instructions in the README file.

BUT THAT IS NOT ALL!

Alas, two things will be missing with the above installation procedure. Thus
not all functionality is included. To get the rest you need the gnu scientific library
(libgsl), the gnu multiple precision library (libgmp), and the (NETCDF)
Network Common Data Form) library

How to implement loops in libRadtran

As you probably already found out, libRadtran does not offer the possibility to loop over input parameters although this is part of everyday life, e.g. to calculate solar irradiance as a function of solar zenith angle, or top-of-atmosphere reflectivity as a function of cloud optical thickness. There are two good reasons for not implementing loops: (a) it would add enourmous complexity to the libRadtran source code if we allowed loops over various input parameters; and more important, (b) there is a nearly infinite amount of scripting languages and tools that allow implementing whatever you have in mind in a much more flexible way than we could ever offer, e.g. scripting languages offered by any Unix Shell (bash, cshell, …) or higher-level languages like Python, Perl, AWK, … or maybe even Excel Macros (haven't tried that but it certainly works). Here is a simple example how you might do that in Unix: Suppose you want to calculate solar irradiance as a function of solar zenith angle. First, create a uvspec input file:

which is exactly what you wanted: Global irradiance as a function of solar zenith angle. Now suppose that you want to do that for thousands of solar zenith angles stored in a file, sza.dat:

1 23.45
2 17.32
3 45.93
4 ...

That is equally simple: Replace the loop in the above script by

for sza in `cat sza.dat | gawk '{print $2}'`; do
...

The line looks a bit weird. cat simple lists the file and gawk (GNU AWK) extracts the second column.
Of course that's not all you can do - please refer to the manuals of bash, sed, AWK, … or whatever you use. You might need to spend some time learning a new language but be sure that it pays off! Everything which has been calculated and published by the libRadtran group has been done in a similar way, sometimes using more weird languages (Perl), sometimes more readable (Python).

How to interpret the radiance output of libRadtran

For those not used to the standard UNIX tools, that may be a pain in the neck! All you want to have are radiances but instead you get

That's the line with the irradiances and actinic fluxes (7 columns) followed by the azimuth angles (here only one column) and then the radiances. What you probably might want is the radiance for each wavelength. This a typical application for an AWK oneliner:

Simple, isn't it? AWK is powerful enough to extract whatever you want, in whatever format you want. It is part of standard Linux installations and of cygwin. Please check the AWK manual if you need more information. Alternatively, there are more modern scripting languages like Python but AWK probably cannot be beat with respect to effectiveness (defined as action done divided by characters typed).

This way you may combine as many aerosol species as you need. The profile_file includes mass concentration altitude profiles and particle size. The netcdf profile_properties_files include the aerosol optical properties (extinction, single scattering albedo, phase matrix, Legendre polynomials of phase matrix … ) and can be generated using e.g. the Mie tool in libRadtran, where you can specify refractive index and size distribution parameters (see examples/MIE_2.INP). Run

bin/mie < examples/MIE_2.INP

and you may use the output wc.mie.cdf as example for an optical properties file.