4b. Input to mcarats executable (b): Namelist mcarWld_nml_init...
Namelist mcarWld_nml_init
Wld_mverb
integer, save :: Wld_mverb = 0
Flag for a verbose mode. Controls verboseness of the executable, (de)activating printing messages. This would be useful for testing and debugging. Options are as follows:
= 0 : quiet (no message will be printed)
1 : yes
2 : more
3 : most (for debug)
Wld_jseed
integer, save :: Wld_jseed = 0
Seed for random number generator (0 for automatic). Should be positive integer, >= 1 and <= 2**31 - 1 if the user specify the seed. This would be useful in some cases (e.g., when debugging).
If Wld_jseed == 0, then the seed is automatically set by the code, using the start date and time. In MPI-parallelized mode, processor element (PE) rank index is also used for the automatic seed, so that every PEs could have completely uncorrelated results. By automatic seed, different results will be obtained trial by trial.
Wld_mbswap
integer, save :: Wld_mbswap = 0
Flag for byte swapping for binary input files (0=no, 1=yes). Input data files can be in binary or text format. For binary files, the code mcarats has capability of instant byte swapping just after reading the data stream. Binary data representation differs by computer architecture. If Wld_mbswap == 1, then every 4 bytes for a datum are rearranged in the reverse order. This is useful when the code mcarats is run on a machine with a different architecture from that of machine on which the input files were created.
Wld_mtarget
integer, save :: Wld_mtarget = 1
Flag for target quantities (computing mode). Options are as follows:
= 1 : flux mode, computing fluxes and heating rates by MC methods
2 : radiance mode, computing radiances by MC methods
3 : volume-rendering mode, computing quasi-radiances (or some signals) by volume rendering
The code mcarats computes only one type of target radiative quantities: This is different from previous versions.
If different types of target quantities (e.g., flux and radiance) are needed for some reasons, then they should be calculated in independent two experiments, by running the mcarats code two times with different I/O files.
Wld_moptim
integer, save :: Wld_moptim = 2
Flag for optimization of calculation techniques. This selects one of built-in presets for technical parameters, which controls trade-off between used computer resources and accuracy (quality) of obtained results. Many technical parameters might not be easy for users to tune. Presets were well tuned by the developer.
Possible options for Wld_moptim are as follows:
= -2 : no tuning (use default optimization)
-1 : no optimization (deactivate all default optimizations)
0 : unbiased optimization (deactivate all biasing optimizations)
1 : conservative optimizations (possibly for smaller biases)
2 : standard optimizations (recommended)
3 : quick-and-dirty optimizations (for speed when small biases are acceptable)
The quality setting can differ by whether the user's goal is accuracy or computation speed. Wld_moptim=0 might be useful for debugging and/or tuning experiments.
If Wld_moptim is not -1, then all values given in the input file are overwritten by the built-in preset. The user can select a preset by Wld_moptim, and then modify the optimization by specifying each parameter value, that overrides the preset, in subsequent namelists.
The following parameters are set by Wld_moptim, automatically:
Wld_dtaumin, Wld_rmlcf, Wld_nplcf, Wld_emtmin,
Sca_nchi,
Atm_taumin, Atm_fsupg, Atm_fsupi, Atm_nzzsup
Sfc_nudsm, Sfc_nurpv, Sfc_nulsrt, Sfc_rrmax, Sfc_rrexp,
Flx_diff0, Flx_diff1,
Rad_zetamin, Rad_difr0, Rad_difr1, Rad_difr0, Rad_difr1,
Pho_wmin, Pho_wmax, Pho_wfac
The preset values are given in source codes, src/mcarats/mcar*.?90.
Wld_njob
integer, save :: Wld_njob = 1
Number of jobs in a single experiment. Here, an experiment corresponds to one namelist input file and one output file. The code mcarats can process multiple jobs in an experiment (a new feature). For each job, a set of namelists mcar*_job should be given consequently.
Namelist mcarSca_nml_init
Sca_inpfile
character(256), save :: Sca_inpfile = ' '
Filename for external file input of tabulated phase function data. Leave it as default ' ' if no external input file is needed.
The file name should have relative path from a directory where the namelist input file exists. For example, when Sca_inpfile = 'mcarats_phs', and the namelist input file is './exp1/mcarats_conf', then actual name of the phase function input file will be './exp1/mcarats_phs'.
See also description of the data in Sca_inpfile.
Sca_mfmt
integer, save :: Sca_mfmt = 1
Flag for format (0=text, 1=binary) of the phase function input file.
If 0, the file should be in sequential access, text format.
If 1, the file should be in direct access, binary format.
IMPORTANT NOTE : Binary format is highly recommended, because the data can be read in faster than text format. In the future versions, it is likely that only binary format files could be accepted.
Sca_npf
integer, save :: Sca_npf = 1
Number of tabulated phase functions that are saved in the data file.
Sca_nskip
integer, save :: Sca_nskip = 0
Number of first data record lines to be skipped. Used only when the data file is in binary format. If this is 100, for example, then first 100 record lines are not read in, line 101 should be angle data, and subsequent (Sca_npf) lines will be read in as phase function data.
Sca_nanci
integer, save :: Sca_nanci = 0
If the file is in binary format, this is the number of ancillary data in a record in the data file. Note that the ancillary data is not used in the mcarats code. Number of data recorded in one record line should be
Sca_nangi + Sca_nanci
If the file is in text format, then Sca_nanci is the number of blocks of ancillary data in one data set. Details are described in subsequent section.
Sca_nangi
integer, save :: Sca_nangi = 1000
If Sca_mfmt == 0 (text format), Sca_nangi is the maximum number of angles for the input table. The number of angles could differ each other phase functions recorded in the file.
If Sca_mfmt == 1 (binary format), Sca_nangi is the number of angles for the input table. The number of angles should be the same for all phase functions recorded in the file.
Sca_ntg -technical parameter-
integer, save :: Sca_ntg = 20000
Number of interpolated table grid points for angles and probabilities. In the mcarats code, every phase functions are interpolated for fine angular grid. For random scattering angle determination, cumulative probability functions are computed, and inverse reference tables are created; Scattering angles are tabulated w.r.t. discrete probabilities. Sca_ntg is the number of their grid points.
Sca_nchi -technical parameter-
integer, save :: Sca_nchi = 4
Number of orders for truncation approximation (>= 2) for anisotropic phase function. The approximation order, ichi, follows
ichi=1 : no truncation approximation
ichi=[2,nchi] : truncation approximation
For higher orders, forward peaks of phase functions are geometrically truncated with larger truncation fractions. The approximation order is determined adaptively depending on photon scattering history. Larger value for Sca_nchi could result in smaller bias, larger size of used memory, and larger noise in results.
Default value is well tuned by Wld_moptim and generally optimal.
Sca_qtfmax -technical parameter-
real(R_), save :: Sca_qtfmax = 20.0_R_
Max scattering angle (degrees) for geometrical truncation of phase functions. Order of truncation approximation is adaptively determined depending on history of photon trajectory. For highest orders, the max angle specified here is used.
Default value is well tuned by Wld_moptim and generally optimal.
Note: Approximation or not?
Some parameters described above activate the truncation approximations which may improve numerical efficiency (trade-off between MC noise and computation time). However the approximations may introduce bias error, which could not be negligible in specific user's problem. If the user would not like to use the approximation (that can be biasing) for some reason, then a required configuration is as Sca_qtfmax=0.
Namelist mcarAtm_nml_init
Atm_inpfile
character(256), save :: Atm_inpfile = ' ' ! file name for input of 3D optical properties
Filename of an external file of 3-D atmospheric model data. Leave it as default ' ' if no 3D atmospheric data are available. 1D atmospheric data can still be given by the namelist mcarAtm_job. The file name should have relative file name path from the directory where the namelist file exists. The file should differ from Sca_inpfile and Sfc_inpfile.
See also description of the data in Atm_inpfile.
Atm_mfmt
integer, save :: Atm_mfmt = 1
Flag for format (0=text, 1=binary) of the atmospheric input file.
If 0, the file should be in sequential access, text format.
If 1, the file should be in direct access, binary format.
IMPORTANT NOTE : Binary format is highly recommended, because the data can be read in faster than text format. In the future versions, it is likely that only binary format files could be accepted.
Atm_np1d
integer, save :: Atm_np1d = 1
Number of scattering components specified with 1-D profile. 1D atmospheric data can still be given by the namelist mcarAtm_nml_job. A single component can be a mixture of gases, aerosols and hydrometeors or a single bin of size distribution.
Atm_np3d
integer, save :: Atm_np3d = 1
Number of scattering components specified with 3-D distribution. The 3-D data are given for horizontally inhomogeneous layers, from the data file (Atm_inpfile). A single component can be a mixture of gases, aerosols and hydrometeors or a single bin of size distribution.
Atm_nx, Atm_ny, Atm_nz
integer, save :: Atm_nx = 1 ! # of X grid points
integer, save :: Atm_ny = 1 ! # of Y grid points
integer, save :: Atm_nz = 1 ! # of Z grid points (layers)
Numbers of grids along x, y, and z-axis, respectively, in the atmosphere.
Atm_iz3l
integer, save :: Atm_iz3l = 1
Lowest layer index of horizontally inhomogeneous layers. Should be >= 1 and <= Atm_nz. Layers for the z-index iz=Atm_iz3l to Atm_iz3l + Atm_nz3 - 1 are defined as horizontally inhomogeneous, and for these layers 3-D data of optical properties are given. See also Atm_nz3.
See here (in Chapter 3) for how homogeneous and inhomogeneous layers are defined.
Atm_nz3
integer, save :: Atm_nz3 = 0
Number of horizontally inhomogeneous layers, which is defined for the z-grid index (layer index)
iz = Atm_iz3l to Atm_iz3l + Atm_nz3 - 1.
See also Atm_iz3l.
Atm_nkd
integer, save :: Atm_nkd = 1
Number of terms for the k-distribution used as the gaseous absorption model. Give Atm_nkd=1 for monochromatic computation.
Atm_mtprof
integer, save :: Atm_mtprof = 0
Flag for temperature profile input. Defines a method to specify temperature data, as follows:
0: temperature data are given for each layer (or at layer mid-levels)
1: temperature data are given for each layer interface
Required number of z-axis levels for temperature data is
Atm_nz for Atm_mtprof=0, or
Atm_nz+1 for Atm_mtprof=1.
Temperature data are used only when the source includes thermal emission (Src_mtype = 2 or 3).
If Atm_mtprof = 0, then the temperature at layer interfaces will be calculated by cubic interpolation within the code. In both cases, Planck function profile within each layer is assumed to be log-linear (i.e. log(B) is linear to the altitude, where B is Planck function).
See also Atm_tmpa1d and Atm_tmpa3d.
Atm_nqlay -technical parameter-
integer, save :: Atm_nqlay = 5
Number of Gaussian quadrature points per layer, used in the local estimation.
The optical thickness along the line of sight can be calculated by Gaussian quadrature (i.e., approximately). This is activated if the ray could penetrate too many cells in a single layer. This happens for a very slant ray or for atmospheric cells with very large vertical-to-horizontal aspect ratio. Exact ray tracing is time consuming under such conditions. Instead, optical thickness along path segment within a layer is calculated by a Gaussian quadrature with Atm_nqlay points. By limiting the number of quadrature points, Gaussian quadrature is efficient even if the ray is very oblique.
Default value is well tuned and generally optimal.
Namelist mcarSfc_nml_init
Sfc_inpfile
character(256), save :: Sfc_inpfile = ' '
Filename of external input file for surface model data. Leave it as default ' ' if no external input file is needed. The name should have relative path from a directory where the configuration file exists.
Surface properties can be specified by some variables in namelist mcarSfc_job or by the external input file. Input data from the external file will override on input the namelist mcarSfc_job.
The file should differ from Sca_inpfile and Atm_inpfile.
See also description of the data in Sfc_inpfile.
Sfc_mfmt
integer, save :: Sfc_mfmt = 1
Flag for format (0=text, 1=binary) of the surface input file.
If 0, the file should be in sequential access, text format.
If 1, the file should be in direct access, binary format.
IMPORTANT NOTE: Binary format is highly recommended, because the data can be read in faster than text format. In the future versions, it is likely that only binary format files could be accepted.
Sfc_nxb, Sfc_nyb
integer, save :: Sfc_nxb = 1 ! # of X grid points
integer, save :: Sfc_nyb = 1 ! # of Y grid points
Numbers of X and Y-pixels for the surface properties. This is now independent of the atmosphere. For example, if Sfc_nxb = 1 and Sfc_nyb = 1, then surface properties are constant in the full domain.
Sfc_mbrdf
integer, save :: Sfc_mbrdf(4) = (/1, 1, 1, 1/)
Flags of on/off status for BRDF models. The four elements correspond to Lambertian, DSM, RPV, and LSRT BRDF models, respectively. Set as 0 if one BRDF model is not used in the simulation. By doing so, computer memory is economically used. If the memory use is not matter, then set all as 1.
Sfc_nsco -technical parameter-
integer, save :: Sfc_nsco = 60
Number of cos(Q0) grid points for surface coefficient table. For each surface finite element, this number of coefficients are stored in a table. The coefficients definitions differ by a type of BRDF.
Sfc_nsuz -technical parameter-
integer, save :: Sfc_nsuz = 200
Number of cos(Q0) grid points for albedo LUTs. Used for look-up tables for a few variables, such as black-sky albedo and incident-direction-dependent maximum BRDF value.
Namelist mcarSrc_nml_init
Src_nsrc
integer, save :: Src_nsrc = 1
Number of radiative sources. Simulation results will be obtained for multiple radiative sources in each single job. Here, for one source, a type (solar, thermal, or local source), location, direction, and source power can be specified.
Namelist mcarFlx_nml_init
Flx_mflx
integer, save :: Flx_mflx = 1
Flag for calculating flux density calculations.
0: no flux output
1: at top and bottom of the atmosphere (TOA and BOA, respectively)
2: at interfaces of all layers except internal interfaces of 3-D inhomogeneous layers
3: at interfaces of all layers
The number of interfaces at which fluxes are computed will be
0 for Flx_mflx=0,
2 for Flx_mflx=1,
Atm_nz - Atm_nz3 + 2 for Flx_mflx=2,
Atm_nz + 1 for Flx_mflx=3.
See also Atm_nz and Atm_nz3.
Flx_mhrt
integer, save :: Flx_mhrt = 1
Flag for calculating heating rate calculations (0=off, 1=on). If Flx_mhrt=1, then heating rates are computed for all Atm_nz layers.
Flx_diff0, Flx_diff1 -technical parameter-
real(R_), save :: Flx_diff0 = 1.0_R_
real(R_), save :: Flx_diff1 = 0.1_R_
Artificial diffusion coefficients for flux and heating rate sampling.
Default values are generally optimal.
Namelist mcarRad_nml_init
Rad_mrkind
integer, save :: Rad_mrkind = 2
Kind of radiance calculated.
= 0 : no radiance calculation
1 : 1st kind, angular distribution of local radiances averaged over each solid angle
2 : 2nd kind, horizontal distribution of radiances averaged over each horizontal cross section of atmospheric column
3 : 3rd kind, angular distribution of radiances averaged over each solid angle and the entire horizontal plane
If Wld_mtarget = 2, Rad_mrkind could be 1, 2, or 3. In the volume rendering mode (Wld_mtarget = 3), Rad_mrkind should be 1 or 2. Specifications of each radiance are given in namelist mcarRad_nml_job.
For the 1st kind, locations of view points in the 3D space, view geometry, FOVs of the detector and angular-pixel mapping method should be specified.
For the 2nd kind, rectangular pixels are defined on the horizontal plane covering the entire domain, and radiances in specific directions are calculated.
For the 3rd kind, radiances are averaged over the horizontal plane covering the entire domain and also averaged over respective solid angles of angular pixels. A pixel mapping method can be chosen in the same way as for the 1st kind. This kind of radiance is calculated by sampling power of photons that penetrates the target area and registering it in appropriate angular bin.
Note that an image "pixel" of output radiance here corresponds to a finite solid angle (1st and 3rd kind) or a finite area on a plane (2nd kind).
Figure. Three kinds of averaged radiances.
Rad_mpmap
integer, save :: Rad_mpmap = 1
A method for pixel mapping (image projection), used for 1st or 3rd kind of radiance. Image coordinates are here defined by U and V. Definitions of them differs by a kind of radiance.
= 1 : rectangular
2 : polar
Photo-like image can be obtained by Rad_mpmap=1. Details are described in the next page.
Rad_mplen
integer, save :: Rad_mplen = 0
Method of calculation of pathlength statistics.
= 0 : (npr = 0) no calculation of pathlength statistics
1 : (npr = Atm_nz) layer-by-layer pathlength distribution (layer air mass factor)
2 : (npr = Rad_nwf) average pathlengths with weighting functions (column air mass factor)
3 : (npr = Rad_ntp) histogram of total, integrated pathlength (time-resolved histogram)
As above, one of three kinds of pathlength information can be calculated. Number of output elements, npr, differs by the kind. See also Rad_nwf and Rad_ntp. Pathlength statistics can be calculated, not depending on Rad_mrkind, the kind of radiance.
Rad_nrad
integer, save :: Rad_nrad = 0
Number of radiance arrays calculated. One radiance array here corresponds to one location and one view region (or direction). If 0, no radiance is calculated.
Rad_nxr, Rad_nyr
integer, save :: Rad_nxr = 1
integer, save :: Rad_nyr = 1
Number of pixels along U and V coordinates, respectively, for radiance images. See Rad_mpmap for the radiance U and V pixel coordinates' definition.
Rad_nwf
integer, save :: Rad_nwf = 1
Number of weighting functions used for column air mass factor. The weighting functions are specified in namelist mcarRad_job and used only when Rad_mplen=2.
Rad_ntp
integer, save :: Rad_ntp = 100
Number of total-pathlength bins. Used only when Rad_mplen=3. Total pathlength is calculated by integrating photon flight length between the source emission point and the detector sampling point. , and radiance contribution is accumulated in appropriate pathlength bin each time of radiance sampling.
See also Rad_tpmin and Rad_tpmax.
Rad_tpmin, Rad_tpmax
real(R_), save :: Rad_tpmin = 0.0_R_
real(R_), save :: Rad_tpmax = 1.0e+5_R_
Minimum and maximum limits, respectively, of total pathlength. Used only when Rad_mplen=3. The pathlength range is divided into bins, number of which is Rad_ntp. Radiance contributions with total pathlength out of the range is not sampled.
Namelist mcarVis_nml_init
Vis_mrend
integer, save :: Vis_mrend = 2
Method for volume rendering (0/1/2/3/4).
= 0 : integration of density along the ray (e.g. for calculating optical thickness)
1 : as 1, but with attenuation (assuming that the source function is uniformly 1)
2 : RTE-based solver, assuming horizontally-uniform source functions
3 : as 2, but taking into accout 3-D distribution of 1st-order source functions (J1)
4 : as 3, but with TMS correction for anisotropic scattering
Higher the value, more physically-correct, high-quality results will be obtained.
Note that the visualization mode is activated only when Wld_mtarget=3 in namelist mcarWld_nml_init. In addition, radiative source for the visualization mode is currently limited to solar and thermal sources: Local source is excluded.
Multiple scattering source functions are calculated by the Picard iteration for a single column with horizontally-averaged optical properties. The visualization modes with Vis_mrend >= 2 are all based on scaled RTE with delta-isotropic approximation (transport approximation).
Example results:
Wld_mtarget =
Vis_mrend =
From above
From ground
3
2
3
3
3
4
2
(reference by MC)
Vis_fatten
real(R_), save :: Vis_fatten = 1.0_R_
Attenuation factor for optical thickness along the line of sight. Should be 1 for physics-based rendering. This might be useful to get nice tone of visualized images, by increasing/decreasing physically-correct optical thickness.
Vis_epserr -technical parameter-
real(R_), save :: Vis_epserr = 0.001_R_
Convergence criterion for multiple scattering components, used only when Vis_mrend >= 2.
Vis_fpsmth -technical parameter-
real(R_), save :: Vis_fpsmth = 0.2_R_
Phase function smoothing fraction for relaxed TMS correction. When Vis_mrend = 4, TMS correction is used to reproduce highly anisotropic radiance angular distribution. The original TMS correction tends to overcorrect the radiance angular distribution when used with delta-isotropic approximation. Therefore, current MCARaTS visualization mode provides an easy method to relax the degree of overcorection. Phase function used for TMS correction is modified to
P_new = 1 - Vis_fpsmth + Vis_fpsmth * P_orig
instead of the original phase function P_orig.
Vis_nqhem -technical parameter-
integer, save :: Vis_nqhem = 1
Number of streams (Gaussian quadrature points) in a hemisphere. Used for the Picard iteration for multiple scattering source function.
Vis_nqlay -technical parameter-
integer, save :: Vis_nqlay = 5
Number of Gaussian quadrature points per layer, for optical thickness integration. This is used when the ray direction is nearly horizontal and/or when the atmospheric cells have very large vertical-to-horizontal aspect ratio. To reduce computational time, Gaussian quadrature will be used for integration of layer optical thickness, instead of cell-by-cell ray tracing.
Namelist mcarPho_nml_init
Pho_iso_SS
integer, save :: Pho_iso_SS = 1
The maximum scattering order, at which photons are allowed to move in the 3-D. Used only when the partially-three-dimensional (P3D) RT solver is selected. The P3D solver allows photons with lower-order of scattering to move in the 3-D. After a scattering or reflection event of the order of Pho_iso_SS, the photon packet never moves in horizontal direction, i.e., independent column approximation (ICA) is used for higher orders.
The solver selection is done when the user run the mcarats executables, by a command line argument.
Pho_iso_max -technical parameter-
integer, save :: Pho_iso_max = 10000000
The maximum order of scattering for simulation. After the scattering of this order, tracing of photon packet will terminate. This might be useful for obtaining approximate results for optically thick, weakly-absorbing atmosphere. For physically-correct results, however, this parameter should be set at a very large value (about 10000 or larger).
This parameter is also useful for obtaining results (Pho_iso_max = 1) with only single-scattering components, for example.
Pho_iso_tru -technical parameter-
integer, save :: Pho_iso_tru = 0 ! min scattering order for truncation approximations
Maximum order of collision for non-approximated radiative transfer simulation. For collision events with order less than or equal to Pho_iso_tru, 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 Pho_iso_tru = 1 forces the direct beams non-approximated and then for multiple scattering the truncation approximations can be used.
Pho_wsml -technical parameter-
real(R_), save :: Pho_wsml = 0.05_R_
Russian roulette weight limit for using local estimates. The local estimation is performed only for photons with large enough weight. For a photon with small weight, the Russian roulette is operated first, before calculating the phase function and ray tracing from the collision point to the detector. This weight threshold is independent of thresholds used in the local estimation modules.
Pho_wmin, Pho_wmax -technical parameter-
real(R_), save :: Pho_wmin = 0.2_R_
real(R_), save :: Pho_wmax = 3.0_R_
Minimum and maximum limits, respectively, for ideal weight of single photon packet. These limits avoid large dispersion in the photon weight. See also Pho_wfac.
Pho_wfac -technical parameter-
real(R_), save :: Pho_wfac = 1.0_R_
Factor to modify the ideal weight of photon packet. The ideal weight is multiplied by Pho_wfac once every 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 should have large enough weight compared to the ideal weight.
Pho_pfpeak -technical parameter-
real(R_), save :: Pho_pfpeak = 30.0_R_
Phase function peak threshold, used for adaptive truncation approximation. Default value is generally optimal.
The adaptive use of truncation approximations is a bit complicated. For every phase functions, multiple truncation approximations are prepared in the preprocess. An order of approximation is adaptively determined, depending on history of each photon trajectory. The approximation order is first initialized for the source emission depending on the isotropy of source emission angular distribution. The order usually increase with the order of scattering. However, actual determination of the approximation order is a bit complicated. The order is increased by one each scattering in a direction that corresponds to small enough value of phase function. If the phase function value is larger than the threshold Pho_pfpeak, the photon is considered as to be redirected to phase function peak direction. Such photons likely contribute to large anisotropy of radiance angular distribution, and high degrees of approximation is not suitable to obtain high accuracy, so that the approximation degree is not changed at the scattering event.