MC-1.8 Update Sep 20, 2022     Contact E-Mail: vmarkel@upenn.edu

Below <VER-NUM> refers to version number, 1.8 for this particular release

=======================================================================

This package is provided 'as is'.
Some functionality is not yet turned on.

Solves Radiative Transport Equation (RTE) by Monte Carlo simulation
in an infinite slab with vacuum outside.

Computes density u(r), current J(r) and specific intensity I(r,s), where:

u(r) = Int[  I(r,s)ds] -- scalar
J(r) = Int[s I(r,s)ds] -- 3D vector

I(r,s) -- specific intensity
r      -- 3D vector of position
s      -- unit 3D vector of direction

Optical parameters are entered in arbitrary physical units called dGt
[Dog Tails]

All distances are specified at input and given on output in one of the
following units:

  a) Units of transport mean free path, ell^*, where
     1/ell^* = mu_a + (1-g)*mu_s

  b) Arbitrary physical units called dGt [Dog Tails], same as were used 
     to define optical parameters of the medium

Results are written to binary or ASCII files. The file extension .bin
or .asc will tell whether the file is binary or not. Binary files can
not be viewed or plotted directly. Instead, one must run the program
dd.exe and specify the binary file name when prompted. dd.exe will
read the binary file and produce ASCII output suitable for plotting in
many different ways. Follow the interactive instructions. Files with
the extension .asc can be viewed or plotted directly. They contain
some basic information in the first lines commented by symbols #. This
symbol indicates that the lines is a comment and not contains
interpret able data by Gnuplot. If using other plotting programs, these
lines may have to be removed.

FEATURES:

* Phase functions:
  a) Heneye-Greenstein phase function with arbitrary g (0<g<1) 
  b) Isotropic scattering (g=0)
  c) Exponential phase function
  d) Other phase functions can be implemented (there are spaceholders)

* Source can be isotropic or collimated, point or infinite front
  (plane wave).

* Histories are traced inside a rectangular box (this box is
  discretized on a rectangular grid), or in cylindrical shells in
  case of cylindrical symmetry. See parameter UseSymmetry. Surface
  can be discretized using rectangular pixels or concentric circles.

* MC runs in a slab zsmin <= z <=zsmax. Currently, only the surface
  z=zsmax is discretized for output, which models transmission-type
  measurements. Reflection is not implemented,. However, one can
  compute all quantities of interest in the layer of voxels adjucent
  to the z=zsmin surface. In this case, Domain='VOL' should be
  selected.

* Source can be placed in the volume or on the surface.

(i)   SourceType='PNTC' : This means the source is concentrated at a
point (at the depth given by parameter z0) and shining in the
direction specified by parameters s0x, s0y, s0z (collimated source).

(ii)  SourceType='PNTI' : This means the source is concentrated at a
point (at the depth given by parameter z0) and shining in all
directions with equal probability (isotropic source).

(iii) SourceType='PLWC' : This means the source is an infinite plane
z=z0 and shining in the direction specified by parameters s0x, s0y,
s0z (plane wave collimated source).

(iv) SourceType='PLWI' : This means the source is an infinite plane
z=z0 and shining in all directions withe equal probability (plane wave
isotropic source).

* In version 1.8, an extensive user manual is not provided. This will
  be part of any future releases. All information that is needed to
  install and run the package (albeit very brief) is contained in
  this file. Future releases (versions 2.*) will include compiler 
  directives for parallelization at the level of individual random 
  walkers (computational efficiency of this approach has yet to be 
  tested).

==================================
AUTHORS, COPYRIGHT AND DOWNLOADING
==================================

(1) All questions regarding the codes should be addressed to Vadim Markel at

              vmarkel@upenn.edu

(2) The package can be downloaded from

              http://whale.seas.upenn.edu/vmarkel/CODES/MC/MC-1.8.tar.gz

	      or

              http://whale.seas.upenn.edu/vmarkel/CODES/MC/MC-1.8.zip

The URL may change from time to time. If the web page is unavailable,
contact me.

(3) This computational package shall be used FOR RESEARCH PURPOSE
    only. Any COMMERCIAL USAGE of full codes or their parts without
    Authors' written consent is PROHIBITED. Modification and/or
    publishing of these codes or their parts in the public domain (for
    noncommercial purpose) is allowed and encouraged, provided that
    proper reference to the original Authorship is retained.

(4) Please acknowledge the use of this package in any scientific
    publication that has made use of it and, if possible, provide a
    link to the URL from which the package has been downloaded.

========================
INSTALLATION AND RUNNING
========================

0. The codes use Intel's MKL library for random number generation and
   have been complied using Intel Fortran Compiler. No other compiler
   or library have been tested. The instructions below are for
   UNIX/LINUX. However, the codes can be installed under other OS's.

1. Download the package MC-<VER-NUM>.tar.gz or MC-<VER-NUM>.zip,
   un-zip or un-gzip and un-tar. This will create the directory

          $PREF/MC-<VER-NUM>/

   where $PREF/ is the directory to which the package was downloaded. Go
   to the above directory.

2. Edit file named Makefile. Make sure that the compilation and link
   options are right for your system, etc.

3. In the directory $PREF/MC-<VER-NUM>/ type

          make all <return>

   This will create executables in the directory
   $PREF/MC-<VER-NUM>/bin/. To install the executables systemwide,
   simply copy them to /usr/local/bin/.

4. Create a working directory (this does not have to be a subdirectory
   in $PREF/MC-<VER-NUM>/). A sample working directory
   $PREF/MC-<VER-NUM>/work/ is provided for convenience.

5. Copy sample parameter files located in $PREF/MC-<VER-NUM>/pars/ to your
   working directory.

6. Edit the parameter files to define the problem you are wishing to
   solve (see below the parameter descriptions).

7. Run the desired executable from the working directory containing
   properly edited parameter files.

===============================
EXECUTABLES AND PARAMETER FILES
===============================

Executable   | What it does               | Output
-----------------------------------------------------------------------
mc           | Computes u(r) AND/OR J(r)  ! u*.bin, J*.bin, I*.bin
             ! AND/OR I(r,theta,phi)      ! or
             ! in a rectangular box   	  | u*.asc, J*.asc, I*.asc
             |                            | 
	     |                            | See parameter NCOMP
.......................................................................
dd           | Reads binary files and     | Data in various
             | converts the data into     | planes or lines through        
             | ACII format for inspection | the medium. Follow run-time 
             | or plotting                | instructions
-----------------------------------------------------------------------

===============================
BRIEF DESCRIPTION OF PARAMETERS
===============================

FILE mc.par [LIST INCOMPLETE]
-----------

1. nmem_tot [integer*8]: Total memory in bytes to be used by an
executable. The executable will not use more memory than specified by
this parameter even if more physical memory is available. Also, any
files written to disk will not exceed in size this amount.

2. nw [integer*8]: Number of random walkers.

3. nr [integer*4]: Length of vectors for all vector
operations. Recommended value 2048.

4. nc [integer*4]: Frequency of reporting progress. Recommended value
1000.

5. seed1, seed2, seed3, seed4 [integer*4]: Seeds for random
streams. Recommended values - more than 1000 each and more than 100
apart (between any two of these numbers).

6. seed5, seed6 [integer*4]: Random seeds used only if
SourceType='PNTI' or 'PLWI'.

FILE rte.par
------------

1. mu_a, mu_s [real*4]: Self-explanatory.  Units are arbitrary but the
   	 		  ratio should be correct.

2. g [real*4]: The asymmetry parameter. Self-explanatory.

3. zsmin, zsmax [real*4]: Monte Carlo process runs in a slab
	 	          {zsmin<=z<=zmax}.  These parameters should
	 	          be given in the units of Units (see below).

4. xbmin, ybmin, zbmin [real*4]: Box in which MC statistics is
   	  	       	  computed. Must lie inside the sample.  If
   	  	       	  computation is done on the surfaces, zbmin,
   	  	       	  zbmax are not referenced.
				  
5. xbmax, ybmax, zbmax [real*4]: See Parameter #4.

6. lx, ly, lz [integer*4]: Discretization of the box for MC
       	      		  bookkeeping. Voxels do not need to be
       	      		  cubic. The volume dimensions are hx, hy, hz,
       	      		  where hx=xmax/lx, etc.  The total number of
       	      		  voxels is lx*ly*lz. The codes will not run
       	      		  if the memory needed to allocate all 3D
       	      		  ararys is larger than what is specified by
       	      		  NMEM_TOT. Choice of voxel size does not
       	      		  affect the MC process, it only affects
       	      		  averaging over trajectories.

7. Rhomax, Lrho [real*4,integer*4]: Maximum radius and the number of
   	   		  cylindrical shells used for bookkeeping if
   	   		  UseSymmetry=T (in the volume or on the
   	   		  surface).

8. z0 [real*4]: Depth of the source. Must be inside the slab or on its
			  surface. If the source is collimated and
			  located on the surface, make sure that it
			  points inside.

9. s0x, s0y, s0z [real*4]: The direction of a collimated source. Does
		          not need to be normalized to unity (the code
		          will normalize it for you).

10. Nscth, Nsphi [integer*4]: Numbers of discrete angles cos(stheta)
    	   		  and sphi/pi. Only used if I(s) is computed.

11. ncomp [integer*4]: Index controlling which of the quantities u(r),
    			  J(r) and I(r,s) should be computed.  This
    			  parameter is allowed to take only the
    			  following values:

			     ncomp   u(r)    J(r)    I(r,s)
			       0       N      N	       N
			       1       Y      Y        N
			       2       Y      N        N
			       3       N      Y        N
			       4       N      N        Y
			       5       Y      Y        Y

    	    	   	    If ncomp=0, MC process runs for timing
			    purposes but no output is written and no
			    memory is allocated. Actual calculation
			    can take noticeably (but not dramatically)
			    longer than the test run with ncomp=0 due
			    to random access to the elements of
			    arrays; this factor can depend on box
			    discretization, compiler options and
			    processor used.


12. SourceType [character*4]: PNTC for point collimated source PNTI
                              for point isotropic source
                              PLWC for plane wave (infinite
                              front) collimated source PLWI
                              for plane wave (infinite
                              front) isotropic source

13. PhaseFunction [character*4]: ISO (isotropic), HG
    		  	  	(Heneye-Greenstein), HG0 (HG
    		  	  	with 0<g<0.01) EXP
    		  	  	(exponential) RAY (Rayleigh -
    		  	  	this one is not currently
    		  	  	implemented)

14. Domain [character*4]: Specifies where the quantities of interest
    		 	  must be computed. Use 'VOL' for 3D volume or
    		 	  'SUR' for computations on the surface.
			  Currently, surface is z=zsmax, that is,
			  modelling transmission.

15. Units [character*8]: Units of length to be used: 'Dog_Tail' or
                         'Ell_star' (read description of units)

16. UseSymmetry [logical*4]: Allowed values are T or F. Indicates
    			  whether to take advantage of the cylindrical
    			  symmetry of the problem (if it is present)
    			  by collecting statistics in cylindrical
    			  shells rather than in cubic voxels.  Applies
    			  to normal incidence OR isotropic sources.