4a. Input to mcarats executable
Executables for radiative transfer simulation are named as "mcarats?d" (?=1, 2, or 3). We call them "mcarats codes" hereafter. All input data of mcarats codes can be given as Fortran namelist variables.
The built-in namelists are as follows:
src : radiation source definitions
tech : technical parameters including tuning parameters for efficiency
integ : integrator (fluxes, heating rates, radiances, camera images, etc) configurations
model : general model configurations
mdlphs : phase function model configurations
mdlsfc : surface model configurations
mdla3d : 3-D atmospheric model configurations
Some large array data such as scattering phase functions and surface and 3-D atmospheric properties can be given by external files:
filephs : phase function model data
filesfc : surface model data
filea3d : 3-D atmosphere model data
The filenames are given in the namelists, mdlphs, mdlsfc, and mdla3d, respectively. The following subsections describes details of each input parameters for the namelists and the external files. There are many input parameters. In addition, this document is not complete. To learn how to set up the parameters for the user's purpose, the easiest way might be to explore the example cases, for which input data files are included in the package. Three cases are provided:
Case 1: three plane-parallel layers, flux and radiance calculations
Case 2: 3-D inhomogeneous case, broken cumulus-type clouds, inhomogeneous diffuse-specular-mixture BRDF model, fluxes and heating rates
Case 3: 3-D inhomogeneous case, overcast stratocumulus cloud, homogeneous Lambertian or Rahman-Pinty-Verstraete BRDF model
Remote sensing ("rs") experiment: calculation of pixel-averaged, reflected radiances at the top of atmosphere (TOA)
Camera image ("ci") experiment: calculation of angle-averaged radiances looking up the sky from a point on the surface
Heating rate ("hr") experiment: calculation of 3-D distributions of pixel-averaged fluxes and volume-averaged heating rates
Point source ("ps") experiment: calculation of narrow FOV fluxes looking up the sky from a point on the surface; the radiation source is artificial laser beam emitted vertically near the detector.
Full list of input parameters
Namelist src
wlen, dwlen, fsrc, dqsrc, thesrc, phisrc, xsrc, ysrc, zsrc, diasrc, jdefsrc, jphisrc,
nsrc, jnorm
Namelist tech
nbyte, nsss, nstrun, nsmax, jtech, wmin, wmax, wfac, nrr, chihi, chilo, fmax, nchi,
diff0, diff1, difh0, difh1, difr0, difr1, difc0, difc1, taumin, dtaumin, emtmin, zetamin,
rlcf, nlcf, fsupg, fsupi, nzzmax, nqsfc, nudsm, nurpv, nulsrt, srmin, srexp,
(pnmin, omgopq, chiiso, trsmin, nxxs, nyys, nzzs, nsle)
Namelist integ
jsflx, jshrt, nrdc, therdc, phirdc, jzrdc, nxr, nyr, ncam, nxc, nyc, xcam, ycam, rmincam,
rmidcam, rmaxcam, jzcam, thecam, phicam, ahcam, avcam, amcam, diacam, npot, nppot, nqpot,
jsppot, xpot, ypot, rminpot, rmidpot, rmaxpot, jzpot, thepot, phipot, pmaxpot, pminpot,
qmaxpot, diapot
Namelist model
nx, ny, nz, iz3l, nz3, xbin, ybin, zgrd, jrfr, jsph, rplanet, jtmplev, tmpa1d, ext1st,
omg1st, jpf1st, ext2nd, omg2nd, jpf2nd, ext3rd, omg3rd, jpf3rd, nkd, wkd, absg1d, dens,
drfr
Namelist mdlphs
filephs, npf, nang, ang, phs
Namelist mdlsfc
filesfc, tmps2d, jsfc2d, psfc2d, nxb, nyb
Namelist mdla3d
filea3d, ifmt3d, npar, tmpa3d, absg3d, extp3d, omgp3d, jpfp3d
Notes on namelist input
The namelist function is a feature of Fortran90, while most Fortran77 compilers (including the GNU compilers) have extensions to read/write namelists. The namelists for mcarats input include many parameters, but the the user does not need to specify all variables' values. This feature makes the Fortran's namelist flexible and easy to use. For example, when the user gives no value for every variables, then default initialization data will be used. It is the case 1 of the examples, where the content of the input file is as the followings:
&src /
&tech /
&integ /
&model /
&mdlphs /
&mdlsfc /
&mdla3d /
This is the case as the sample case 1 (see examples/case1/conf), in which flux profile is simulated for a plane parallel weakly-absorbing cloud. Default initialization data are defined in ./src/mcarats/artdinput.inc, and they are customizable before compiling.
The user can partially set values for one variable in the namelist. For example, a sentence,
absg1d(1:10,1)=4.0e-5, 3.0e-5, 2.0e-5, 1.0e-5, 5*1.0e-6
sets values for a part of the 2-D array variable absg1d(iz,ikd), which may be declared as a very large array in the source code.
Another feature of Fortran namelist is a freedom of ordering of each member variable in a namelist block. Any order is acceptable in one namelist block. For details, see Fortran language reference for the compiler.
Namelist src
jnorm
[integer scalar]
When jnorm=1, all output radiative quantities are normalized by domain-average source flux, as follows:
area-averaged fluxes: F/F0
volume-averaged heating rates: H/F0
area-averaged radiances: pi*I/F0
angle-averaged local radiances (camera image): pi*I/F0
local plane/spherical fluxes: F/F0
When the source is collimated solar beam (jdefsrc=1) alone, for example, the domain-averaged source flux is
F0 = fsrc * abs(cos(180 - thesrc))
where fsrc is the incident irradiance on the plane normal to the solar beam, and thesrc is the zenith angle of the incoming beam.
nsrc
[integer scalar]
Number of source definitions.
jdefsrc
[integer 1-D array, {dat(isrc), isrc=1, nsrc}]
Defines external and/or internal sources, as follows:
0: localized sources (the location, direction, and angular width are specified by the user)
1: solar sources (incidence from the top of atmosphere)
2: solar plus thermal emission sources
3: thermal emission sources.
wlen
[real 1-D array, {dat(isrc), isrc=1, nsrc}]
Wavelength (micrometer) of light for thermal emission. This is used only when jdefsrc = 2 or 3. If the band width (dwlen) is not zero, then wlen is the lower limit of the band. See also dwlen.
dwlen
[real 1-D array, {dat(isrc), isrc=1, nsrc)}]
Wavelength band width (micrometer). Null is acceptable. When dwlen=0, the simulation is completely monochromatic, and output quantities are spectral ones. Otherwise (dwlen > 0), output quantities are also spectrally integrated ones, and spectrally integrated thermal emission are calculated (jdefsrc=2 or 3).
fsrc
[real 1-D array, {dat(isrc), isrc=1,nsrc}]
Spectral source irradiance or power.
When the solar source is present (jdefsrc = 1 or 2), fsrc is the solar source spectral irradiance (W/m^2/micrometer) at the top of atmosphere. The fsrc is defined as integrated on the plane normal to the center direction of the source emission. Note that the definition differs from the spherical flux (or mean radiance). The top-of-atmosphere solar source irradiance on the horizontal plane should be, for collimated solar incidence (dqsrc=0),
fsrc*abs(cos(180 - thesrc))
When the source is localized (jdefsrc = 0), fsrc is the emitted spectral power (W/micrometer).
Even if dwlen > 0, fsrc should be spectral quantity, averaged over the band. Then spectrally integrated solar source irradiance should be dwlen*fsrc, for example.
If jnorm=1, then calculated results will be normalized, and thus any value for fsrc should produce the same output.
dqsrc
[real 1-D array, {dat(isrc), isrc=1,nsrc}]
Half cone angle (in degree) that determines angular width of solar or localized source, used only when jdefsrc = 0, 1 or 2. This should be 0.2665666 (degree) for solar incidence at an annual-mean state of the sun-earth system. Give zero for cases in which sources are negligibly small or infinitely far.
thesrc, phisrc
[real 1-D array, {dat(isrc), isrc=1,nsrc}]
Zenith and azimuth angles (in degree), respectively, of the source emission direction vector. Used only when jdefsrc = 0, 1 or 2. Note the source direction is defined as transport direction of source light. If the source is solar light, then the transport direction corresponds to the sun-to-surface vector. Thus, the solar zenith angle should be (180 - thesrc).
jphisrc
[integer 1-D array, {dat(isrc), isrc=1, nsrc}]
If jphisrc = 0, then the azimuth angles of the source vectors are set as phisrc. Else if jphisrc = 1, then the azimuth angles are set as random between 0 to 360 degrees.
xsrc, ysrc, zsrc
[real 1-D array, {dat(isrc), isrc=1,nsrc}]
Coordinates that specifies the location of the localized source, used when jdefsrc=0.
diasrc
[real 1-D array, {dat(isrc), isrc=1,nsrc}]
Diameter of the emitting source surface (or the surface of the outmost lens of the artificial source), when the source is localized (jdefsrc = 0). The localized source should be very small compared to the model domain, but non-zero finite size is allowed. If diasrc = 0, then it means the source is from a point. Otherwise, the source surface is assumed to be spherical. This parameter, diasrc, is related to dqsrc and the diameter (D) of the emitting sphere, as follows:
diasrc = D * sin(dqsrc) if dqsrc < 90 degrees
diasrc = D otherwise
Note on output quantities and physical units
jnorm=1: Output quantities are all normalized as described above.
jnorm=0: Output quantities have physical units.
a) dwlen=0: spectral, monochromatic calculations, as the followings
area-averaged spectral fluxes (e.g., W/m^2/micrometer),
volume-averaged spectral heating rates (e.g., convergences, W/m^3/micrometer),
area-averaged spectral radiances (e.g., W/m^2/steradian/micrometer),
angle-averaged, local spectral radiances (e.g., W/m^2/steradian/micrometer), and
local plane/spherical fluxes (e.g., W/m^2/micrometer)
b) dwlen > 0: spectrally-integrated calculations; Units do not include "1/micrometer".
Namelist tech
nbyte
[integer scalar]
# of length of single binary record for one "real*4" value in direct access format files. Used when an external input file for 3-D model data is recorded in direct-access format (ifmt3d=1). In other cases (ifmt3d=0), this variable is not used at all. An appropriate value for nbyte is computer's architecture and compiler dependent (usually 4 or 1). If you use the GCC g77 compiler on a x86 PC, nbyte should be 4. If you use Intel Fortran compiler (on x86 PC or other machines), then nbyte should be 1. See also ifmt3d.
nsss
[integer scalar]
Order of collision that determines RT scheme shift when the partially-three-dimensional (P3D) RT solver is selected. The solver selection is done when the user run the mcarats executables (see [[here>User's Guide v0.9.5/Page 6]] for details). After a scattering or reflection event of the order of nsss, the photon packet never moves in horizontal direction, i.e., independent column approximation (ICA). In other solvers, this parameter has no effect on simulations.
nsmax
[integer scalar]
Maximum order of collision. After the scattering of the order, energy of photon packet will be forced to null, and the simulation for that packet will be terminated. This might be useful for optically thick, weakly-absorbing atmosphere. For precision, however, this parameter should be set at a very large value (about 10000 or larger).
nstrun
[integer scalar]
Maximum order of collision for non-approximated radiative transfer simulation. For collision events with order less than or equal to nstrun, no truncation approximation is used. The approximation can introduce (usually very small) bias. Thus this parameter might be useful for some purposes. For example, if the user need to get accurate separation of direct-beam and multiple scattering, then setting as nstrun = 1 forces the direct beams non-approximated and then for multiple scattering the truncation approximations can be used.
jtech
[integer scalar]
Switch to select one of built-in presets for technical parameters described in the followings. Many parameters in the /tech/ namelist might be difficult for non-power users to tune. Presets were well tuned by the developer. The preset can be selected by specifying jtech, as follows:
-1: No preset is used. the user may specify all /tech/ variables' values.
0: No technique that can improve numerical efficiency is used. This might be useful for debugging and/or tuning experiments.
1: Preset for high-quality radiances of out-of-aureole directions
2: Preset for high-quality radiances of inner-aureole directions
3: Preset for low-quality radiances
4: Preset for high-quality flux/heating-rates
5: Preset for low-quality flux/heating-rates
6: Preset for good-looking camera images using quick-and-dirty methods
For "low-quality" calculations, quick-and-dirty methods are used. The quality setting can differ by whether the user's goal is accuracy or computation speed.
If jtech is not -1, then all values given in the input file are overwritten by the built-in preset. The following parameters are set automatically:
chilo, chihi, fmax, nchi, wmin, wmax, wfac, nrr, taumin, dtaumin, rlcf, nlcf, zetamin,
diff0, diff1, difh0, difh1, difr0, difr1, difc0, difc1, nudsm, nurpv, nulsrt, nqsfc,
srmin, srexp, emtmin, fsupg, fsupi, nzzmax
The preset values are given in src/mcarats/artsettech.f.
The followings in the namelist tech can be automatically set by jtech
chihi
[real scalar]
Upper limit of the directionality parameter, chi, used for the dual-end truncation approximation (Iwabuchi, 2006, JAS). The parameter chi is 1 for collimated radiation (solar direct beam) and 0 for isotropic light. For chi > chihi, no truncation approximation is used. The truncation fraction linearly increases with decreasing chi from chihi to chilo. Setting as 0.6 < chihi < 0.9 is recommended. See also chilo and fmax.
chilo
[real scalar]
Lower limit of chi for regime shift in truncation approximations. For chi < chilo, the truncation fraction is fixed at each value prescribed for each scattering phase function. Setting as 0.2 < chilo < 0.6 is recommended. See also chihi and fmax.
fmax
[real scalar]
Scaling factor determining maximum delta-fraction of the dual-end truncation approximations, for chi larger than or equal to chilo. The approximation reduces computation time of fluxes and heating rates by 10-80% and also significantly improves accuracy of computed radiances by reducing noises by a factor of 10 (for cloud reflectance at visible wavelengths). Recommended value is between 0.6 and 0.8. See also chihi and chilo.
nchi
[integer scalar]
Number of truncation approximation regimes, one of which corresponds to one range of chi. Should be larger than or equal to 3, i.e., at least three regimes are used:
chi > chihi: no truncation approximation
chiiso < chi < chihi: dual-end truncation approximation
chi < chiiso: delta-isotropic approximation
wmin, wmax
[real scalar]
Minimum and maximum limits, respectively, for ideal weight of single photon packet. These limits avoid large dispersion in the photon weight.
wfac
[real scalar]
Factor to modify the ideal weight of photon packet. The ideal weight is multiplied by wfac once every nrr collision events. If the weight of photon packet is less than the ideal weight, then the Russian roulette method is applied and photon population is reduced. Thus survived photon packets have increased weight that is the same as the ideal weight. See also nrr.
nrr
[integer scalar]
The ideal weight is multiplied by wfac once every nrr collision events.
taumin
[real scalar]
Minimum threshold of vertical optical thickness of the total atmosphere. If actual optical thickness is less than this threshold, then the collision forcing method is used, and the scaled value of the total optical thickness is set to taumin. Recommended value is between 2 and 10.
dtaumin
[real scalar]
Minimum threshold of vertical optical thickness of single layer. If actual optical thickness of one layer is less than this threshold, then the collision-forcing method is used in the layer, and the scaled value of the optical thickness is set to dtaumin. Thus collision events are forced to occur with prescribed probability even in very optically thin layer. Usually recommended value is 0.01 for heating rate calculation.
rlcf
[real scalar]
Scale length (m) for Local Collision-Forcing (LCF), which forces artificial collisions at locations near the cameras. Extinction coefficients are scaled so as to be large near the camera. See also nlcf.
nlcf
[integer scalar]
Power exponent for LCF. Should be 1 or 2 usually.
Scaled extinction coefficients (B_ext1) will be
B_ext1 = max(B_min, B_ext)
for original extinction coefficient B_ext, and the min extinction coefficient is
B_min = dtaumin / dz_lay * (zdif / rlcf)**nlcf
where dz_lay is a layer geometrical thickness and zdif is height difference from the camera location. See also rlcf and dtaumin.
zetamin
[real scalar]
Minimum threshold for each energy contribution sampled by the local estimation method, which is used for calculating area-averaged radiances, angle-averaged local radiances (the camera image), and local fluxes. Radiance contribution from each emission/scattering/reflection event is calculated as the normalized angular distribution function multiplied by transmittance between the event point and the detector. Recommended value is 0.3.
diff0, diff1
[real scalar]
Artificial diffusion coefficients for flux sampling. Recommended setting is as diff0=1 and diff1=0.1.
difh0, difh1
[real scalar]
Artificial diffusion coefficients for heating rate sampling. Recommended setting is as difh0=1 and difh1=0.1.
difr0, difr1
[real scalar]
Artificial diffusion coefficients for area-averaged radiance sampling. Recommended setting is as difr0=50 and difr1=0.01.
difc0, difc1
[real scalar]
Artificial diffusion coefficients for angle-averaged local radiance (camera) sampling. Recommended setting is as difc0=50 and difc1=0.01.
nudsm
[integer scalar]
Number of solar zenith angles for the look-up tables (LUTs) for diffuse-specular-mixture (DSM) BRDF model. The LUTs contains parameters for albedo calculation and determination of reflection direction. In simulations, the parameters used are interpolated from the LUT. Thus larger nudsm value achieves higher accuracy but requires larger memory for the LUTs.
nurpv, nulsrt
[integer scalar]
Same as nudsm, but for Rahman-Pinty-Verstraete (RPV) and Li-Sparse-Ross-Thick (LSRT) BRDF models, respectively.
nqsfc
[integer scalar]
Number of quadrature points for surface albedo calculations for the BRDF models, DSM and RPV models. Used when creating the LUTs for albedo, which is calculated by integration of the BRDF over the hemisphere. Larger quadrature points can achieve accurate results but may take longer CPU time. Usually 10 is enough to achieve high accuracy as 0.5% (relative unit).
srmin
[real scalar]
Parameter for determination of reflection direction by the BRDF models, DSM and RPV models. Smaller value needs less computer time, but the determined reflection direction is more approximate. If srmin is very large (>1.0e+8), then no such an approximation is used, and the simulation may require nearly infinite CPU time! Should be larger than or equally to 1. Usually 4 is recommended.
srexp
[real scalar]
Parameter for determination of reflection direction by the BRDF models, DSM and RPV models. Smaller value needs less computer time but the determined reflection direction is more approximate. If srexp=1, then no such an approximation is used, and the simulation may require nearly infinite CPU time! Should be between 0 and 1. Usually 0.5 is recommended.
emtmin
[real scalar]
Minimum threshold for photon populations of thermal emission in single layer. Used only when jdefsrc=2 or 3. This forces to emit photons with prescribed probability even from very optically-thin layer. Should be between 0 and 1. Recommended setting is emtmin=0.01. If emtmin=0, then no such an optimization is used.
fsupg
[real scalar]
Geometrical threshold parameter for automatic super-cell generation for maximum cross section method. Usually should be about 2. See also fsupi.
fsupi
[real scalar]
Inhomogeneity threshold parameter for automatic super-cell generation for maximum cross section method. An optimal value would be 1.3. A super-cell is generated by merging cells util one of conditions are met.
nzzmax
[integer scalar]
Possible max mumber of layers merged into a single super-cell, in which the maximum cross section method is used.
Note: Approximation or not?
Some parameters in the namelist "tech" activate approximations which may improve numerical efficiency (accuracy vs computation time). However the approximations may introduce bias error. If the user would not like to use any approximation (that can be biasing) for some reason, then a required configuration is as jtech=0, and no biasing method will be used (unbiasing methods are still used).
Note on transformations of scattering phase functions
Transformations of scattering phase functions (so-called truncation approximation) will be used according to values for chihi, chilo, chiiso, and fmax. Note that the transformation will speed computation and reduce Monte Carlo random noises but produce (usually small) bias error, so there is 'trade-off' of accuracy and CPU time. The recommended parameter set for general purpose can be selected by jtech.