LIDORT F90_S is a multilayer multiple scatter radiative transfer code, the newest in the series of
LIDORT models from R. Spurr at the SAO. It is the first code in Fortran 90. It is based on the older FORTRAN 77 code LIDORT V2.3S [1-3]. The new code is much more than a translation - there has been a complete reorganization of storage variables, input/output and error handling, and the package has an important new feature (multiple solar beam capability). Validation for plane parallel atmospheres may be done against the DISORT code [4,5].
The capabilities are:
 pseudo-spherical solar beam attenuation [2]
 delta-M scaling [6]

Nakajima-Tanaka single scattering computation [7]
 arbitrary viewing geometry and optical depth output
 downwelling and/or upwelling output

Flux/mean-intensity output options
 multiple scatter layer source term output [2,3,8]
 multi-solar beam output [9]
The multi-beam capability is especially useful for sensitivity testing, as it allows the model to produce a great deal of output at one call. RTE homogeneous solutions and matrix inversion for the boundary-value problem need to done only once, no matter what the solar zenith angle.
These are the two most time-consuming tasks, and can be completed first before any beam solution computation. When the beam particular integrals have been found, the boundary value solutions follow from simple back-substitution. Another feature that saves time is that Fourier series convergence is done separately for each solar zenith angle, so that calculations for an already-converged solar beam solution do not need to be carried out alongside those still required for a solution that has still not converged.
Inputs to LIDORT F90_S have been simplified and streamlined compared to those in the F77 code. I have dispensed with some of the more confusing inputs in the F77 package, or left them in as "specialist options" that can be used in exceptional circumstances. Two remarks: (1) the default option in LF90 is pseudo-spherical - plane-parallel is now a specialist option; (2) the earlier F77 code had two solution methods for the particular beam integrals (the classical substitution method, and the Green's function method [2,10]) - the new code only uses the
Green's function method (this is mathematically more powerful and completely analytic).
There are many more internal checks on the inputs, and the error handling now produces two types of input checks - fatal and warning. Fatal input mistakes will abort the LIDORT call; for each mistake, there is a description of the mistake and an action on how to fix it. A warning check will allow LIDORT to proceed after it has made some internal changes to some incorrectly specified input flags - you will get a warning output which tells you what your input mistake was and how LIDORT fixed it internally. For a fatal error in the execution, you will get a message and a subroutine trace through the code.

The LF90_S.tar package unfolds to give the following 5 directories, and 2 subdirectories: makestuff sourcecode testruns
|_______ library
|_______ modules
USERGUIDE
DISORTCHECK
Go into the testruns directory. If you have one of platforms listed below, you can compile and link the code immediately. Just type one of the two instructions (depending on your shell script):
../makestuff/makelidort.csh
../makestuff/makelidort.sh and this will create the following files in testruns:
LF90test.exe library/libsourcecode_archive.a
(executable)
(source code object archive)
(module objects, 12 files) modules/*.mod
The program will carry out a number of tests: The first test uses the input test files (control and physics) with the label Test_example1 ; other tests are Test_example2 , etc. The final test is a check against DISORT, and uses control and physics input files with name disortcheck . This produces a file disortcheck_physics.dat
, which is used in subdirectory DISORT_CHECK as input to a DIISORT CALL. If you type LF90test.exe
, then the program should produce a number of output files called
Test_example1_input.out
Test_example1_results.out
Test_example1_scenario.out
Test_example2_input.out
Test_example2_results.out
Test_example2_scenario.out
.............. disortcheck_results.out disortcheck_physics.dat
These should be the same as the set of files with extension “out_s”, which were supplied as part of the package. This is the installation test.
The first test is for output at 7 solar zenith angles, 8 view zeniths, 5 optical depths, and 5 relative azimuths: a total of 1400 radiances. There were 13 computational layers in the atmosphere and
12 discrete ordinate streams. On a modern computer this calculation takes a fraction of a second.
Performance: 14 times faster than DISORT.

3.1 USERGUIDE
Contains Word 2000, PDF and PS files of this document.
3.2 sourcecode
This contains complete source code listings for the package, including all module collections (4 of them) and code collections (5 of them). The listing is:
Module collections: parameter_modules.f90 inputoutput_modules.f90 beam_modules.f90 generic_modules.f90
2 modules constants
3 modules input/output
3 modules
4 modules workspace, beam workspace, general
Subroutine collections:
1. multibeam_masters.f90
2. multibeam_solutions.f90
3. generic_solutions.f90
4. auxilaries_f77.f
5. optional_readinput.f90
2 routines
30 routines
14 routines
LAPACK/ASYMTX F77 code
6 routines
F90 Top level
F90
F90
F90 optional
There are 12 modules in all, grouped as shown. For the subroutines, the first 4 collections are the basic code. The 5th collection is just an aid to reading some (but not all) of the input variables, using the FINDPAR tool, but if you have your own code to set LIDORT inputs, you might not want this collection.
There is an undigested rump of FORTRAN 77 modules, collected in auxilaries_f77.f
. This contains the ASYMTX eigen-solver code, and a bunch of routines from the LAPACK collection
(for solving linear algebra). All F77 routines are stand-alone - no F90 module dependencies.
3.3 makestuff
This directory contains all material necessary to build the code. The listing is
Makefile make.flags make.patterns make.sources make.targets makelidort.csh* makelidort.sh*
(do not need to change)
(do not need to change)
(do not need to change)
File make.sources contains instructions for the source code compilations and archiving, while make.patterns contains module dependencies. You should not need to alter either of these . make.targets contains some “clean” instructions for deleting all object files and archives
.

Calling one of the shell-script files will compile and link the code as noted above in Section 2.
If you want to change the name of your calling MAIN program (called LF90test_main.f90) or the name of the executable (called LF90test.exe
), go into the Makefile itself and change just the names.
Compiler options for various platforms are set up in make.flags. If you want to add a platform or change the compilation flags, go inside this file and do the necessary. Currently configures for
5 platforms as follows:
# Compaq/Alpha, f95 compiler
# SGI 32 bit, f90 compiler
# Sun/Solaris, f95 compiler
# Linux, pgf90 compiler
# Linux, Intel ifc compiler
3.4 testruns
This is the home directory. It contains the following:
LF90test.exe
LF90test_main.f90
Executable
Calling program library/ modules/
Subdirectory
Subdirectory
(once you have created it) plus a number of test example files, such as:
Test_example1.control_inp
Test_example1.physics_inp
Test_example1_fourier.out_s
Test_example1_input.out_s
Test_example1_results.out_s
Test_example1_scenario.out_s input input output output output output
The subdirectory /library will contain just one file - an archive of all the compiled source code subroutines and the calling program.
The subdirectory /modules will contain a number
(12) of files - all the compiled source code modules end up here.
These two subdirectories will be empty when you download the package. Compiling the code will fill them up. If you want to start afresh (remove executable and object files), then type:
../makestuff/makelidort.csh clean
../makestuff/makelidort.sh clean (alternative)
The calling program is designed to work with the tests as described briefly in the section on installation. Inside the calling program, the sequence is extremely simple for one test:
Start
Read the input file (e.g. Test_example1.control_inp)
Read the physics file (e.g. Test_example1.physics_inp)
Call the LF90 master routine (beam_masters)
Stop

3.4 DISORTCHECK
Contains the following routines
DISORTCHECK/BDREF.f
DISORTCHECK/DISORT_v2.f
DISORTCHECK/ErrPack.f
DISORTCHECK/LINPAK.f
DISORTCHECK/RDI1MACH.f
DISORTCHECK/disortcheck.f
DISORTCHECK/disortcheck.results_s
DISORTCHECK/disortcheck_physics.dat
DISORTCHECK/machmod.f
DISORTCHECK/makefile
The “ makefile ” will compile and link all source code modules (extension “.f”) and create an executable “ disort
”. This is a very simple “build”, with no compilation flags and should run on most platforms. The environment for this test is disortcheck.
f, which was written to ingest file disortcheck_physics.dat
and produce results disortcheck.results_s.

To get some familiarity with the code, it is useful to study the 4 Module collections, particularly the first two in the above list. The breakdown is as follows.
4.1. parameter_modules.f90
There are 2 modules here:
- parameters_precision parameters_precision parameters_constants
This is a small file, which allows you to set the floating-point precision for the whole package.
This is a very useful F90 feature that was not present in F77. The current default is double precision.
- parameters_constants
This contains numbers like 1.0, pi, etc, and all the symbolic dimensioning parameters (this version of the code does not use allocatable memory in any explicit way). The key dimensions that you might want to change (depending on memory requirements) are: max_solar_beams max_comp_layers max_comp_streams max_input_moments max_user_streams maximum number of solar beams 10 maximum number of computational layers 15 maximum number of computational streams 10 maximum number of phase function moments 100 maximum number of viewing zenith angles max_user_relazms max_user_opdeps max_offgrid_opdeps
10 maximum number of relative azimuth angles maximum number of optical depth outputs
7
6 maximum number of off-grid op. depth outputs 5
All other dimensions are fixed or dependent upon the basic set. Some remarks: a) max_comp_streams is the maximum number of discrete ordinate streams in the half space. b) max_user_opdeps is not restricted, and you might want to set this equal to the number of computational layers + 1 in order to get output at every level boundary. c) max_offgrid_opdeps is for output at non-boundary optical depths. It should always be less than max_user_opdeps . d) max_input_moments is applicable to both the diffuse and single-scatter calculations, and in particular if you are doing a single-scatter correction you might want to use a large number of moments in order to get full phase function accuracy for this calculation. For the diffuse scatter, the phase function is truncated according to the number of discrete ordinates (computational streams). In any case this parameter should be at least TWICE max_comp_streams .
4.2. inputoutput_modules.f90

There are 3 modules here: inputs_general inputs_beam outputs_results
The two input modules contain declarations of all the variables and flags that you need to supply.
All results are collected in the output module (intensities, Fourier terms, multiple scatter layer source term output, flux/mean-intensity). The solar beam inputs have been separated from the
"general" inputs.
Each input file is divided into three groups: essential, specialist and debug inputs. Looking at the file-read input example below will show you how to set the variables according to your specification.
- inputs_general
! ESSENTIAL INPUT (BOOLEAN)
! -------------------------
Pairs of flags marked with an “m” are mutually exclusive.
do_fullradiance Flag for output of full radiance field
do_transmittance_only Flag for doing a transmittance calculation
do_doubleconv_test Flag for double convergence test on azimuth Fourier series.
Not normally required if you use the single-scatter correction
(see below)
do_lambertian_albedo Flag for Lambertian surface
do_deltam_scaling Flag for using the delta-m scaling m do_additional_mvout Flag for additional mean-value output (no top of radiances etc ) m do_mvout_only
do_upwelling
do_dnwelling
Flag for mean-value output only. Just fluxes….
do_user_zeniths
do_user_azimuths
Default: should be set.
Default: should be set. If flux-only option has been set, this flag
will be turned off internally + warning issued m do_user_opdeps If you want optical depth output at arbitrary values, set this flag m do_lbound_opdeps Flag for output at layer boundaries
! ESSENTIAL INPUT (NUMBERS)
! -------------------------
! computational layers and discrete ordinate streams
INTEGER :: n_comp_streams number of HALF-SPACE discrete ordinates
INTEGER :: n_comp_layers
INTEGER :: n_input_moments number of computational layers number of phase function Legendre moments
REAL (KIND=dp) :: flux_factor
REAL (KIND=dp) :: accuracy_criterion solar flux convergence criterion for Fourier series

REAL (KIND=dp) :: zenith_tolerance
INTEGER :: n_user_zeniths
INTEGER :: n_user_relazms
REAL (KIND=dp) :: user_zenith_inputs
REAL (KIND=dp) :: user_azimuth_inputs
INTEGER :: n_user_opdeps
REAL (KIND=dp) :: user_opdeps_inputs
do_quad_output
! DEBUG INPUT
! -----------
do_write_input
do_write_scenario
do_write_fourier
do_write_results
Closeness of zenith cosines to 1.0
number of viewing zenith angles number of relative azimuth angles viewing zenith angles in degrees number of output optical depths optical depth input values
INTEGER :: user_bounds_inputs
! SPECIALIST INPUT
! ----------------
do_mssterms
do_all_fourier
Layer boundaries for output
Flag for output of multiple layer source terms
Flag for output of all Fourier terms relative azimuth angles in degrees
Flag for (additional) output at computational stream angles
Flag for printing input summary
Flag for printing input scenario summary
Flag for printing Fourier terms (radiances only).
If a beam solution has already converged, no output is given
Flag for printing Output results
CHARACTER (LEN=60) :: & ! Output file names. Error file names should be specified.
results_write_filename, &
input_write_filename, &
scenario_write_filename, &
fourier_write_filename, &
error_inputcheck_filename, &
error_inputwarning_filename, &
error_execution_filename
! ESSENTIAL GEOPHYSICS INPUT
! --------------------------
REAL (KIND=dp) :: omegas_input
REAL (KIND=dp) :: deltaus_input layer single scattering albedos layer optical thickness values
REAL (KIND=dp) :: phasmoms_input
REAL (KIND=dp) :: albedo
! SPECIALIST GEOPHYSICS INPUT
! --------------------------- layer phase function Legendre coefficients
Lambertian albedo
REAL (KIND=dp) :: brdf_comp_diffuse
REAL (KIND=dp) :: brdf_user_diffuse
BRDF at input computational angles, output computational angles for each Fourier term
BRDF at input computational angles, output

- inputs_beam
! ESSENTIAL INPUT (BOOLEAN)
! ------------------------- viewing zenith angles for each Fourier term
do_sscorrection Flag for N-T single scatter computation
! ESSENTIAL INPUT (NUMBERS)
! -------------------------
INTEGER :: nbeams
REAL (KIND=dp) :: toa_sunzen
REAL (KIND=dp) :: earth_radius
REAL (KIND=dp) :: height_grid
! SPECIALIST INPUT
! ---------------- number of solar zenith angles solar zenith angles in degrees earth radius in [km] height grid in [km]
do_plane_parallel
do_refractive_beam plane-parallel option (use for DISORT check) refractive beam option. NOT FUNCTIONAL V3.0.
do_own_chapman
! SPECIALIST GEOPHYSICS INPUT
! ---------------------------
Flag for doing your own Chapman function input.
REAL (KIND=dp) :: pathtaus_input
REAL (KIND=dp) :: local_sunzen
REAL (KIND=dp) :: brdf_comp_beam
Only needs to be set if you are doing your own
Chapman function calculation . local layer solar zenith angles (only with refractive beam option) . NOT FUNCTIONAL V3.0
BRDF at input solar angles, output computational angles for each Fourier term
BRDF at input solar angles, output viewing zenith angles for each Fourier term
REAL (KIND=dp) :: brdf_user_beam
- outputs_results
INTEGER :: fourier_saved
REAL (KIND=dp) :: intensity
REAL (KIND=dp) :: mean_intensity
Number of Fourier terms used, each solar angle radiances by optical depth, view zenith, view azimuth, solar beam, direction
Mean intensities by optical depth, solar beam, direction
Fluxes by optical depth, solar beam, direction REAL (KIND=dp) :: flux_output
REAL (KIND=dp) :: mscatsterm Multiple scatter layer source terms by layer, view zenith, view azimuth, solar beam, direction
REAL (KIND=dp) :: mscatboa_sourceterm Bottom of atmosphere diffuse scatter source terms by view zenith, view azimuth, solar beam. Upwelling only
REAL (KIND=dp) :: directboa_sourceterm Bottom of atmosphere direct beam source

REAL (KIND=dp) :: intensity_f
REAL (KIND=dp) :: mscatsterm_f terms by view zenith, view azimuth, solar beam. Upwelling only
Fourier component values
Fourier component values
REAL (KIND=dp) :: mscatboa_sourceterm_f Fourier component values
REAL (KIND=dp) :: directboa_sourceterm_f Fourier component values
4.3. Workspace modules
There are two groups here, one for the general solution and one for the beam solution. generic_modules.f90 workspace_generic_bookkeeping workspace_generic_errorhandling workspace_generic_solutions workspace_generic_setups
Variables in this group of modules are independent of the solar forcing terms. The first two are explicit; “bookkeeping” variables arise from processing the input into forms that the scattering code will take. “Setups” has variables stored after routines to perform delta-m scaling, and to compute and store transmittance factors. “Solutions” contains Legendre functions, results from the solution of the homogeneous discrete ordinate RTE, the inverted boundary value problem matrix; and some of the post-processing variables defined for arbitrary viewing geometry. beam_modules.f90 workspace_beam_setups workspace_beam_solutions workspace_beam_singlescatter
These are variables associated only with the solar beam forcing term. “Setups” stores transmittance factors and multipliers for the post processing solution of the solar beam.
“Solutions” stores the Green’s function solution of the particular integral, and contains postprocessed variables for this solution. “Singlescatter” stores variables only for the N-T single scatter computation, which succeeds the main, multiple scatter code.

We summarize briefly the subroutines in the source code. The breakdown is as follows.
5.1. multibeam_masters.f90
There are 2 modules here: beam_master fourier_beam_master
“ beam_master
” is the main calling routine, the one that is called from your environment. It contains the main Fourier loop, inside of which there is the call to “ fourier_beam_master
”.
5.2. generic_solutions.f90
There are 14 modules here:
5.3. multibeam_solutions.f90
There are 30 modules here:
5.4. auxiliary_F77.f
Collected here are the untranslated F77 routines. Apart from the double precision “ASYMTX” eigenvalue subroutine, all others are taken from LAPACK, and they are used only for solving the boundary value problem.
5.5. optional_readinput.f90
There are 6 modules here:

This file is Test_example1.control_inp
. Not everything is specified here, in particular, the geophysics inputs are not specified, as they usually come from a setup operation involving atmospheric quantities. Files like these are read by the source-code file optional_inputs.f90
, which uses the FINDPAR tool for parameter read.
=====================
Module inputs_general
=====================
ESSENTIAL INPUT (BOOLEAN)
-------------------------
LIDORT - Do full radiance calculation? t
LIDORT – Do transmittance only? f
LIDORT - Perform double convergence test? f
LIDORT - Lambertian albedo? t
LIDORT - Include Delta-M scaling? t
LIDORT - Generate mean value output additionally? t
LIDORT - Generate only mean value output? f
LIDORT - Upwelling output? t
LIDORT - Downwelling output? t
LIDORT - User-defined zenith angles? t
LIDORT - User-defined azimuth angles? t
LIDORT - User-defined optical depths? f
LIDORT - Layer boundary optical depths? t
ESSENTIAL INPUT (NUMBERS)
-------------------------

LIDORT - Number of half-space streams
6
LIDORT - Number of atmospheric layers
13
LIDORT - Number of input Legendre moments
40
LIDORT - Solar flux constant
1.0
LIDORT - Accuracy criterion for Fourier series convergence
0.001
LIDORT - Zenith tolerance level
0.00001
LIDORT - Number of user-defined relative azimuth angles
5
LIDORT - User-defined relative azimuth angles ( degrees, [0-180] )
0.0
45.0
90.0
135.0
180.0
LIDORT - Number of user-defined zenith angles
8
LIDORT - User-defined zenith angles ( degrees, [0-90) )
0.1
5.0
10.0
15.0
20.0
25.0
30.0
35.0
LIDORT - Number of user-defined optical depths
4
LIDORT - User-defined optical depths
0.0
0.1
0.5
0.9
LIDORT - Number of layer boundary optical depths
5
LIDORT - Layer boundaries for optical depth
0
4

8
11
13
SPECIALIST INPUT
----------------
LIDORT - Output multiple scatter layer source functions? f
LIDORT - Compute all Fourier components? f
LIDORT - Include quadrature angles in output? f
DEBUG INPUT
-----------
LIDORT - Input control write? t
LIDORT - Input scenario write? t
LIDORT - Output results write? t
LIDORT - Output Fourier component write? f
LIDORT - filename for results output
Test_example1_results.out
LIDORT - filename for input write
Test_example1_input.out
LIDORT - filename for scenario write
Test_example1_scenario.out
LIDORT - filename for Fourier output
Test_example1_fourier.out
LIDORT - filename for Input check errors
Test_example1_inputcheck.out
LIDORT - filename for Input warning errors
Test_example1_inputwarning.out
LIDORT - filename for Execution crash errors
Test_example1_lidortcrash.out
==================
Module inputs_beam
==================
ESSENTIAL INPUT (BOOLEAN)

-------------------------
LIDORT - Do single scatter correction? t
ESSENTIAL INPUT (NUMBERS)
-------------------------
LIDORT - Number of solar beams
7
LIDORT - Solar beam zenith angles
30.0
45.0
60.0
70.0
75.0
80.0
85.0
LIDORT - Earth radius (km)
6371.0
SPECIALIST INPUT
----------------
LIDORT - Plane-parallel treatment of solar beam? f
LIDORT - Do your own Chapman function calculation? f
LIDORT - Beam path with refractive atmosphere? f

A simple example will illustrate the construction of optical property input. We consider two types of scattering (molecular and particulate), and include trace gas absorption for one species.
Each layer is assumed optically uniform. We consider the Rayleigh scattering coefficient

Ray
(independent of layering), a layer air column density D p
in layer p , which depends only on the pressure difference across the layer (hydrostatic equilibrium). We assume the gas absorber has absorption coefficient
 p
in layer p , and the trace gas partial column density is U p
. The particulate scatterer is assumed to have extinction optical thickness
 p
in layer p , and scattering optical thickness
 p
. The total extinction optical thickness and single scatter albedo required for
LIDORT is:
 p
 
Ray
D p
  p
U p
  p
;
 p

 p
 
 p
Ray
D p
;
For molecular (Rayleigh) scattering, the phase function has a cos
2
 dependence on scattering angle

, with phase function Legendre coefficients


 

 

 
where
 
is the depolarization ratio For spherical particulate matter, a Mie calculation will yield the required coefficients, which we will call
We have
 p 0 combined total phase function moment


= 1. . [The definition of coefficients is pl pl
, where index l goes from 0 to some maximum value.
 l
(LF90) = (2
required for LIDORT is l +1)
 l
(DISORT)]. Then the
 pl

 p

 pl p
 
Ray
 
Ray
D p
 l
D p
;
In the pseudo-spherical approximation, it is necessary to know slant path optical depths for the solar beam before the primary scattering. These may be determined based on a geometrical calculation of slant path distances through each layer (a Chapman function calculation, depending on earth radius and height array information). There is an internal function for this task, and the result is the array of solar beam optical thickness values pathtaus_input(0:n,k,b). For each layer n , we have k = 1,… n , and b is the solar beam index.. We have pathtaus_input(0,0,b) = 0 (top of atmosphere values). If you do your own
Chapman function calculation, you must also supply this input array. The above considerations do not apply for a plane-parallel atmosphere, where slant paths are equal to vertical paths divided by the cosine of the solar zenith angle.

[1] Spurr, R.J.D., T.P. Kurosu, and K.V. Chance, A Linearized discrete Ordinate Radiative
Transfer Model for Atmospheric Remote Sensing Retrieval, J. Quant. Spectrosc. Radiat.
Transfer , 68 , 689-735, 2001.
[2] Spurr, R.J.D. Simultaneous derivation of intensities and weighting functions in a general pseudo-spherical discrete ordinate radiative transfer treatment, J. Quant. Spectrosc.
Radiat. Transfer , 75 , 129-175, 2002.
[3] van Oss, R.F., and R.J.D. Spurr, Fast and accurate 4 and 6 stream linearized discrete ordinate radiative transfer models for ozone profile retrieval, J. Quant. Spectrosc. Radiat.
Transfer , 75 , 177-220, 2002.
[4] Thomas, G., and K. Stamnes, Radiative Transfer in the Atmosphere and Ocean, 1 st
ed.,
Cambridge University Press,1999.
[5] Stamnes, K., S.-C. Tsay, W. Wiscombe, and K. Jayaweera, Numerically stable algorithm for discrete ordinate method radiative transfer in multiple scattering and emitting layered media, Applied Optics , 27 , 2502-2509 (1988).
[6] Wiscombe, W., J. Atmos. Sci ., 34 , 1408-22 (1977).
[7] Nakajima, T., and M. Tanaka, Algorithms for radiative intensity calculations in moderately thick atmospheres using a truncation approximation, J. Quant. Spectrosc.
Radiat. Transfer , 40 , 51-69, (1988).
[8] Spurr, R. LIDORT V2PLUS, a comprehensive radiative transfer package for nadirr viewing spectrometers, Proceedings SPIE conference, Barcelona (2003).
[9] Stephens paper
[10] Siewert, C., A concise and accurate solution to Chandrasekhar’s basic problem in radiative transfer, J. Quant. Spectrosc. Radiat. Transfer , 64 , 109-130, 2000.