Differences

This shows you the differences between two versions of the page.

--- basic_usage [2012/09/24 11:09]
admin
+++ basic_usage [2015/08/24 16:16]
claudia [How to setup an input file for your problem (checklist)]
@@ Line 1: / Line 1: @@
 ===== 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/experimental/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
+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/experimental/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.
+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.
@@ Line 11: / Line 26: @@
 ===== 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__:
+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. 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.
+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).
+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.
+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.
+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. **ozone_column** which modifies the ozone column, or **co2_mixing_ratio**, ...
+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.
+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**
+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**
    0  0
 0.1 10
@@ Line 39: / Line 130: @@
       0  0
   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.
+The first is a water cloud with effective droplet radius of
+<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
+<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**.
+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 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 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 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**.
+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!
+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.
+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
-  solar_file ../data/solar_flux/atlas_plus_modtran
+  source solar    ../data/solar_flux/atlas_plus_modtran
   wavelength 450
@@ Line 81: / Line 217: @@
 .000  1.681501e+03  2.247862e+02  0.000000e+00  1.338096e+02  4.674322e+01  0.000000e+00
 .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
+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
+.7<html>&plusmn;</html>20.0 and for the diffuse downward
+.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
-.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.
+.1<html>&plusmn;</html>2.4 for the direct and
+.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
+. 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
-  solar_file ../data/solar_flux/atlas_plus_modtran
   source thermal
-  correlated_k fu
+  mol_abs_param fu
   wavelength_index 7 18
-  output sum
+  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
+For the diffuse downward irradiance we obtain
+.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
+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
@@ Line 107: / Line 270: @@
   atmosphere_file ../data/atmmod/afglus.dat
-  solar_file ../data/solar_flux/atlas_plus_modtran
+  source solar  ../data/solar_flux/atlas_plus_modtran
   wavelength 400
@@ Line 118: / Line 281: @@
   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
+Here we are looking straight upward from the surface in the blue (400
-.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.
+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
+.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.
+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:
+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
-  solar_file ../data/solar_flux/atlas_plus_modtran
+  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 pseudo-spherical
+As you know, the plane-parallel approximation in disort is not very
-  rte_solver sdisort
+accurate for low sun (here: SZA 88 degrees). With the default solver
-we obtain 35.45 instead which is considerably different. Now add the following to the input file:
+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
+  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 sdisort 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
+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
+.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 sdisort 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).
+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
+Using spherical MYSTIC you may safely compute radiances and
-  mc_backward_output ...
+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
-  solar_file ../data/solar_flux/atlas_plus_modtran
+  source solar ../data/solar_flux/atlas_plus_modtran
   wavelength 300
@@ Line 157: / Line 355: @@
 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
+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
+% 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
@@ Line 167: / Line 372: @@
 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
+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
+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
@@ Line 178: / Line 392: @@
 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.