                              
                 8. Installing mcml and conv
     
     This  chapter  provides  the  instructions  on  how  to
install the software.  software installationSince both  mcml
and  conv  are written in ANSI Standard C, they in principle
should  be able to be compiled on any computer systems  that
support  ANSI C.  Subject to the computer systems  available
to this laboratory, we will only provide the executables for
Sun  workstations, IBM PC compatibles, and Macintoshes.   On
Sun  SPARCstations  2, we have compiled the  mcml  and  conv
using  the  ANSI  C (acc).  On IBM PC compatibles,  we  used
Microsoft  QuickC.   And on Macintoshes,  we  used  Symantec
THINK  C.   We will provide the source code, users can  feel
free  to  compile  them on their computer systems.   Consult
corresponding manuals for information on how to compile  the
code.
     
     As   Monte   Carlo   simulations  are   computationally
intensive, we suggest that you use workstations such as  Sun
SPARCstations  on which you can submit background  jobs  and
which  provide  high  speed  computation.   The  convolution
program  is  also more pleasant to use if you  have  a  fast
computer,  although  it  is not as computation-intensive  as
Monte Carlo simulations.


8.1  Installing on Sun workstations

     
     The  distribution disk is an IBM format double  density
3  1/2"  disk, which Sun SPARCstation 2 should  be  able  to
read.    The  disk  includes  three  directories:  mcmlcode,
convcode, and Sun.  The directory mcmlcode includes all  the
source  code  of mcml and the makefile used  for  acc.   The
directory convcode includes all the source code of conv  and
the   corresponding  makefile.   You  need  to  modify   the
makefiles  for  other  compilers  (See  Appendix  C).    The
directory Sun includes all the executables, a template  file
of  mcml  input  (template.mci), a sample mcml  output  file
(sample.mco),  and  a short manual (mcmlconv.man)  which  is
Chapter 8-10 of this manual.
     
     To  install the source code of mcml and conv, make  two
directories called mcml and conv respectively.  Then,  while
in  the  directories  mcml or conv,  copy  the  files  under
mcmlcode  and  convcode  to the directories  mcml  and  conv
correspondingly using command mcopy, e.g.:

     mkdir mcml
     cd mcml
     mcopy -t "a:mcmlcode/*" .

where the option "-t" means text transfer and the period "."
represents the current directory.  More information  can  be
retrieved using "man mtools".  Use this command to copy  the
text files in directory Sun to your working directory.
     
     To install the executables, copy the executables to the
sub  directory  ~/bin  under your home directory  using  the
command  mcopy  without options.  Then,  put  the  directory
~/bin  under the search path in .cshrc or .login if you  are
using  C  Shell.   Consult manual if  you  are  using  other
shells.
     
     Having  finished copying, you can eject the disk  using
the command eject.  If your Sun workstation does not have  a
floppy drive, you can transfer the files through a networked
IBM  PC  or  a  compatible.  If you have an electronic  mail
address, we can also send the package to you through mail.


8.2  Installing on IBM PC compatibles

     
     For IBM PC's or compatibles, the distribution disk is a
double density 3 1/2" disk.  An alternative  5 1/4" disk can
be  sent upon request.  The disk includes three directories:
mcmlcode,  convcode,  and  IBMPC.   The  directory  mcmlcode
includes  all  the  source  code  of  mcml.   The  directory
convcode  includes  all  the  source  code  of  conv.    The
directory  IBMPC  includes all the executables,  a  template
file of mcml input (template.mci), a sample mcml output file
(sample.mco),  and  a short manual (mcmlconv.man)  which  is
Chapter  8-10  of  this  manual.   The  executables  include
mcml.exe  and  conv.exe.  The code was compiled  and  linked
using Microsoft QuickC 2.5.  The executables will be able to
detect whether your computer has math coprocessor, and  take
advantage of the math coprocessors if they are present.
     
     The simplest installing process would be:

     xcopy a: c:/s

where  /s  means  copying  the subdirectories  if  they  are
present.    This   command  will  make  three   directories:
mcmlcode, convcode and IBMPC, and copy all the files in each
directory.
     
     If  you  want to be able to execute the programs  under
any  directory, you should put the directory  IBMPC  in  the
search  path.  The search path can be changed  in  the  file
autoexec.bat.


8.3  Installing on Macintoshes

     
     For  Macintoshes,  the distribution disk  is  a  double
density  3  1/2"  disk.   The disk includes  three  folders:
mcmlcode,  convcode, and Mac.  The folder mcmlcode  includes
all  the  source code of mcml.  The folder convcode includes
all  the  source code of conv.  The folder Mac includes  all
the   executables,   a   template   file   of   mcml   input
(template.mci), a sample mcml output file (sample.mco),  and
a  short manual (mcmlconv.man) which is Chapter 8-10 of this
manual.    The   executables  include  mcml.fpu,   conv.fpu,
mcml.020,  conv.020,  mcml.000, and conv.000  for  different
types of computers as discussed subsequently.
     
     To  install the source code of mcml and conv, make  two
folders  called mcml and conv respectively.  Then, copy  the
files  under mcmlcode and convcode to the folders  mcml  and
conv correspondingly.
     
     Before  you install the executables, you need  to  know
what  kind  of  Macintosh you are using.  You can  test  the
following conditions to decide which executables to use:
  
  A.  MC68040
  
  B.  MC68020 or MC68030
  
  C.  MC68881 or MC68882

If  your Macintosh meets condition A, or conditions B and C,
you should copy the executables with extensions ".fpu".   If
your  Macintosh meets condition B only, you should copy  the
executables with extensions ".020".  Otherwise,  you  should
use the executables with extensions ".000".  We suggest that
you  remove the extensions of the executables on  your  hard
drive to keep consistency with the manual.


8.4  Installing by Electronic Mail

     
     For these users who have electronic mail access on UNIX
machines,  we  can  deliver  the  software  package  through
electronic mails.  The package is archived using the command
tar,  compressed  using the command compress,  then  encoded
using the command uuencode before it is mailed out using the
mail utilities.  After you receive the mail, you need to  do
the following.
  
  1.     Save the mail as a file, e.g., mc.mail.
  
  2.      Decode  the  file (mc.mail) to get  a  file  named
     mc.tar.Z using

     uudecode mc.mail
  
  3.      Uncompress  the  file mc.tar.Z  to  get  the  file
     mc.tar

     uncompress mc.tar.Z
  
  4.      Unarchive  the  file mc.tar  to  get  the  package
     using:
     
     tar -xvfo mc.tar

At  this moment, you should have three directories under the
working directory.  They are mcmlcode, convcode, and Sun, or
IBMPC, or Mac.
     
     If  you ordered a Sun version of the package, you  only
need  to  put  the executables under the proper  directory.,
e.g., ~/bin (see Section 8.1).
     
     If  you  ordered an IBM PC version or a Mac version  of
the  package, you need to transfer the files to  your  local
computer using FTP or modem.  Then refer to Section  8.2  or
8.3 for details.
     
     It  is  appropriate to describe in more detail  how  we
send  the package through electronic mails which is  exactly
the opposite of the above procedure.  We put the package  in
a  working  directory  which include  three  subdirectories:
mcmlcode, convcode, and Sun, or IBMPC, or Mac.  Then:
     
     tar -cvf mc.tar
     
     compress mc.tar
     
     uuencode mc.tar.Z mc.tar.Z > mc.mail
     
     mail your_address

In  the  mail  utility, you can add in any messages  in  the
beginning of the mail, then you need to use the command r to
read  in  the file mc.mail.  Then, you can send the file  by
typing  a  period "." and a return in a new  line  (see  the
manual page of mail).
                              
                  9. Instructions for mcml
     
     This  chapter describes the actual instructions to  use
mcml.  Macintoshes, IBM PC compatibles and UNIX machines are
used  as  examples of computer systems, although   mcml  can
execute  on any computer systems that support ANSI  Standard
C.   The reader is assumed to be familiar with the operating
system and comfortable with at least one of the text editors
on  the  computer system to be used to execute mcml.   Three
steps involved in the Monte Carlo simulation using mcml  are
included in the following sections: preparing the input data
file,  executing the program mcml with the input data  file,
processing  the output data in the data files named  in  the
input data file.  We will also show some known bugs.


9.1  File of input data

     
     The  first step to do the simulation using mcml  is  to
prepare  an  input  data file (e.g., "filename.mci")file  of
input  data.   Any  valid filenames on your  system  without
spaces   will  be  acceptable,  but  extension   ".mci"   is
recommended.   In  ANSI C, spaces are  used  as  separators.
Therefore,  filenames with spaces may  not  be  accepted  by
mcml,  although  they are allowed by some operating  systems
themselves  such  as  the Macintosh  System.   We  will  use
"filename.mci" as an example in the following discussions.
     
     This  input  data  file  may be edited  with  any  text
editors  such  as  Apple Edit, MockWrite or  Microsoft  Word
Wordon  Macintoshes, Norton editor NE or Microsoft  Word  on
IBM  PC  compatibles, vi editor or EMACS  on  UNIX  systems.
However, if you use word processors like Microsoft  Word  to
edit  the  file, make sure that you save the  file  in  text
format since mcml does not accept binary files as input.  If
you are using the UNIX system and are uncomfortable with  vi
or  other editors available on UNIX, you can use editors  on
your  personal computer, then transfer the file using Kermit
if  you use modem or FTP if your personal computer is  on  a
network.   Make  sure  to use ASCII or text  mode  when  you
transfer this file.
     
     The  best way to write an input data file is to make  a
copy   of  the  template  file  called  "template.mci"  (See
Appendix  D), then modify the parameters in the  file.   The
input  data  file is organized line by line.  All parameters
must  be  in the right order.  The lines with parameters  in
order must also be in order themselves.  However, feel  free
to  insert comment lines or space lines in between  to  make
the file more readable.  Comment lines start with the symbol
"#".   The  symbol "#" can also be used after the parameters
in a line to mark the start of comments.
     
     The  parameters in the input data file are read by mcml
line  by line.  If there are multiple parameters in a  line,
use  tabs  or spaces to separate them.  A tab is  preferred,
because  it  aligns  the parameters for better  readability.
All  dimensional  quantities are in cm or derived  from  cm.
The  thickness  of  each layer is  in  cm.   The  grid  line
separations  are  also  in cm.  Absorption  coefficient  and
scattering coefficient are in 1/cm.  Each line of the  input
file is explained in the order that they appear in the input
data file as follows.
  
  1.   File  version  of  the input data file.   Always  use
     "1.0" for now.
  
  2.   Number of runs (integer).  Each run is an independent
     simulation.  You can specify any number of runs,  which
     is  not subject to memory limit.  Make sure you use  an
     integer  instead  of a floating point number  for  this
     parameter, e.g., 5 instead of 5.0.
  
  3.   Output filename and file format.  Extension ".mco" is
     recommended    for   the   output   filenames,    e.g.,
     "output1.mco".    The  program  mcml   currently   only
     supports ASCII format, therefore always use "A" as  the
     second parameter in this line.  Make sure that you  use
     different output filenames if you have multiple runs in
     an  input  data  file, although mcml  checks  for  this
     mistake.   What is more important is that the filenames
     should  not  be the same as the names of existent  ones
     unless  you  want  to overwrite the existent  files  on
     purpose.   Since the program mcml does not  check  this
     error, you will lose the existent files.
  
  4.  Number of photon packets to be traced (integer).
  
  5.   Separations (in cm) between grid lines  in  z  and  r
     direction of the cylindrical coordinate system.   These
     are  floating  point numbers.  Both z and  r  originate
     from  the photon incident point on the surface of first
     layer,  and  the  z axis points down  into  the  turbid
     medium.  Make sure these parameters are large enough to
     give  you  an acceptable variance, and small enough  to
     give  you  an acceptable resolution.  These  parameters
     should  be  determined coordinately with the number  of
     photons to achieve both accuracy and resolution.   Also
     note that users should try to choose grid size in the z
     direction so that grid boxes do not cross tissue-tissue
     interfaces or boundaries (see Section 9.5).
  
  6.   Number  of  grid  elements (integers)  in  the  z,  r
     directions of the cylindrical coordinate system and  in
     the  alpha direction, where alpha is the angle  spanned
     between  the  photon exiting direction and the  surface
     normal.   Since the angle always covers  0  through  90
     degrees,  the angular separation is 90 degrees  divided
     by  the  number of angular grid elements  specified  in
     this  line.  Be careful with this line, if the  numbers
     are too large, the output file will be very big because
     2D  arrays are written into the output file.  If you do
     not  need to resolve one of the directions (z or r)  or
     the angle, use 1 (not 0) for that parameter.  Make sure
     to use integers for these three parameters.
  
  7.   Number  of  layers (integer).  This number  does  not
     include the ambient media above or below the tissue.
  
  8.   Refractive  index for the top ambient   medium  above
     the first layer (e.g., 1.0 for air).
  
  9.   Layer parameter lines.  One line for each layer.   In
     each  line  are  the refractive index,  the  absorption
     coefficient (1/cm), the scattering coefficient  (1/cm),
     the  anisotropy  factor, and the  thickness  (cm).   To
     simulate   semi-infinite  tissue,  use  a  very   large
     thickness  (e.g., 1E8 cm) compared with the  mean  free
     path of the tissue.
  
  10.   Refractive index for the bottom ambient medium below
     the last layer (e.g., 1.0 for air).
  
  11.   Repeat lines 3 through 10 for each additional run if
     you have multiple runs.
     
     Note:  Two points are worth noting.  The only limit  to
the  number  of  grid elements and layers is the  amount  of
memory  allocated to mcml in your system because the  arrays
are dynamically allocated according to these parameters.  Do
not use floating point numbers for the integers.  Otherwise,
the  program  may interpret them incorrectly.  However,  you
may  use  integers  for floating point  numbers,  e.g.,  100
instead of 100.0.


9.2  Execution

     
     Once  the input data file is prepared, the program mcml
can  be executed using the input data file.execution  During
the  execution,  the  program mcml  will  report  an  output
message which gives the number of photons remaining  in  the
simulation, the number of runs left, and the time of  ending
the  job.   The first report is after 10 photon packets  are
traced,  then  it is updated when every 1/10  of  the  total
number  of  photon  packets  are  traced.   The  methods  of
execution  are  slightly  different on  different  operating
systems.


Macintosh

     
     To  run mcml on Macintosh System 6, you have to copy or
move  the  executable mcml to your working folder where  the
input data file resides, then double click on the mcml  icon
to  start the program.  The program mcml will prompt for the
input  data filename, which is entered through the keyboard.
If  the  input  data file cannot be found, the program  will
prompt you again until it finds the file or a period "."  is
typed,  where "." is used to abort the program.  If you  use
Macintosh System 7, you may use an alias of mcml instead  of
a copy of it.


IBM PC compatibles

     
     For  IBM  PC compatibles, make sure that the  directory
with  mcml is in the search pathpath, search, which  can  be
checked   by   typing  the  command  "path"  or   the   file
"autoexec.bat".  To run mcml with the input data file  as  a
command parameter under DOS command prompt,  type:
     
     mcml filename.mci

If  you  want  to save the output message as a  file  (e.g.,
message.out), type:
     
     mcml filename.mci > message.out

which   redirects   the   output   message   to   the   file
"message.out".   To run mcml in the interactive  mode,  type
the following command without input data filename:
     
     mcml

Then, the program mcml will prompt for the input data file.


UNIX

     
     On  a UNIX system, you should place the executable mcml
in  a  directory that is in the search path.  The  directory
~/bin  is  a good choice.  The search path can be found  and
modified  in the file ".cshrc" if you are using C  Shell  or
the  file  ".login".  The three ways of invoking mcml  under
DOS can be used under UNIX operating systems.  Moreover,  if
you  wish to discard the messages during the execution,  use
the command:
     
     mcml filename.mci > /dev/null

which  redirects the output to the "bit bucket" (/dev/null).
You   can   also  simply  submit  a  background   job   job,
backgroundusing:
     
     mcml filename.mci > /dev/null &
     
     Refer to your UNIX manual for how to inquire about  the
status  of a background job.  If you are still in  the  same
session,  the  command  "jobs"  can  be  used  in  C  Shell.
Otherwise, you should use the UNIX command "ps" to check for
background  processesprocess,  background.   You  can   also
directly  look for the output files to check if the  job  is
done.


9.3  File of output data

     
     When  the job is completed, the results will be written
into  the output data files file of output dataas you  named
in your input data file.  A sample output data file is shown
in  Appendix E.  The output data files can be read with  any
text editors if they are ASCII as a result of using "A"  for
the file format in the input data file.  They may be big  if
your numbers of grid elements are large.
     
     The contents of output files are self explanatory.  The
same  policy for the input data file is used for the  output
data file, that is, comment lines starting with a symbol "#"
and  space  lines are written to the file for clarity.   The
first  line  is used for file type identification  when  the
file  is  read by other applications.  Then, the  user  time
spent  on  the  simulation is reported in  a  comment  line.
Then, a few categories of data are reported sequentially  in
the  following order: pure numbers, 1D arrays and 2D arrays.
The  definitions of the output data can be found in  Chapter
4.   The  category "InParm" reports all the input parameters
specified  in the input data file again so that  the  output
file  is  a complete reference and the input parameters  may
also  be double checked against any errors in the input data
file.   The category "RAT" reports the specular reflectance,
the total diffuse reflectance, the total absorption, and the
total  transmittance.  The category "A_l" is the  absorption
as   a  function  of  layer.   The  category  "A_z"  is  the
absorption as a function of depth z.  The categories  "Rd_r"
and  "Rd_a"  are the diffuse reflectances as a  function  of
radius  r  and  angle  alpha respectively.   The  categories
"Tt_r"  and  "Tt_a" are the transmittance as a  function  of
radius r and angle alpha respectively.  The 2D arrays  A_rz,
Rd_ra,  and Tt_ra are then reported.  The category  A_rz  is
the  absorption as a function of depth z and radius r.   The
categories  Rd_ra and Tt_ra are correspondingly the  diffuse
reflectance and transmittance as a function of radius r  and
angle  alpha.   The name of each category is written  before
the  data, such that the data can be easily identified.  The
units for these data were discussed in Chapter 4.


9.4  Subset of output data

     
     Sometimes, only a subset of the output data  is  needed
for presentation or processing.  For example, we may need to
print  a  1D  array  into a file in XY  format,  namely  two
columns  of data, or a 2D array in XYZ format.  These  files
can  then be read into some commercial applications such  as
AXUM  on IBM PC compatibles and KaleidaGraph on Macintoshes.
This  subset extraction extraction, subsetcan be done  using
another  program that we have partially completed  --  conv.
The program conv is intended to read in the output data file
of  mcml  that  gives responses of infinitely narrow  photon
beam,  and  convolve  the output data if  the  responses  of
finite  size beam are to be computed.  The program conv  can
output  the  original data or the convolved data in  various
formats.  The convolution part of the program conv  has  not
been finished, although it can be used to extract subsets of
the original output data.
     
     The  program conv is made to be interactive.  After the
program  is  invoked, the menu system will direct  the  data
input,  output, or process.  On Macintosh, copy or move  the
program  conv to your working folder.  Start conv by  double
clicking  on  the  icon.   On IBM  PC  compatibles  or  UNIX
machines, invoke the program conv by typing:
     
     conv

Follow  the  menu  to  input  an  mcml  output  file  (e.g.,
"filename.mco").  Then, output specific data to  new  files.
However,  for  the sake of efficiency, we wrote  a  C  Shell
script   file   "conv.bat"  for  UNIX  users.    For   shell
programming,  refer  to Anderson et  al.  (1986)  or  Arthur
(1990).   A  similar file can be written on MS-DOS operating
system.  The file "conv.bat" is used for fast batch process.
For  example, if there are several mcml output  files  named
"outfile1.mco",  "outfile2.mco"... "outfilen.mco",  and  you
need  to  select the diffuse reflectance as  a  function  of
radius  r of these mcml output files on a UNIX system,  then
you can use the command:
     
     conv.bat "outfile*.mco" Rr

This  command takes two arguments.  The first one gives  the
mcml output files to be processed.  If wild cards, such as *
or  ?,  are  used, the argument has to be within  quotes  to
prevent immediate file expansion.  The second argument gives
the  type of subsets to be extracted.  In this case,  it  is
the  diffuse reflectance as a function of r.  The  files  of
the  subsets  will be named as "outfile*.Rr".   In  each  of
these output files, there are two columns, the first one  is
the radius, and the second one is the reflectance.  To check
the complete usage of "conv.bat", type "conv.bat" on command
line.  More examples are:
     
     conv.bat "outfile*.mco" Az

for  1D   absorption as a function of z.   In  each  of  the
output   files  of  this  command,  there  are  two  columns
representing z and the internal absorption respectively.
     
     conv.bat "outfile*.mco" Azr

for  2D absorption as a function of z and r.  In each of the
output  files  of  this  command, there  are  three  columns
representing z, r, and the internal absorption respectively.
     
     If  you  use  UNIX  to do the simulation  and  want  to
present  the  results using Macintosh or IBM PC compatibles,
transfer  the smaller subset files using KERMIT if  you  use
modem or FTP if you use Ethernet.


9.5  Bugs of mcml

  
  1.   Users  have  to  be careful with several  known  bugs
     about  the program mcml version 1.0.  If a grid element
     crosses   a  medium  interface,  e.g.,  a  glass/tissue
     interface,  the  photon  absorption  within  this  grid
     element  is  considered  to be the  absorption  in  the
     medium where the center of the grid element is located.
     Therefore,  if the center is on the side of the  glass,
     mcml   may  report  small  absorption  in  the   glass.
     Sometimes, this problem may be avoided by choosing  the
     z-grid  system  carefully so  that  the  boundaries  of
     elements align with the layer interfaces.
  
  2.      The  user time of a simulation can be reported  as
     zero  if the simulation is long enough to overflow  the
     timer   (See   the  function  clock()   in   the   file
     "mcmlmain.c").
  
  3.      The  input parameters in the input data file  have
     to be in the order as specified.  Furthermore, you have
     to use integers for number of photon packets, number of
     layers,  and number of grid elements in the input  data
     file.   If  floating  point numbers  are  inadvertently
     used, mcml can not detect the error and may read in the
     wrong parameters.
     
     If you find any new bugs, please report to us using the
information  in  Appendix G -- "Where  to  Get  the  Program
mcml".   It  is  very important that you provide  us  enough
information about the bug so that we can reproduce it.
                              
                  10. Instructions for conv
     
     This  chapter  describes the instructions  to  use  the
program   conv,  which  is  used  to  convolve  the  impulse
responses of mcml  over incident beams of finite size.  This
program reads the output of mcml, then convolves the impulse
responses  according to the user specified  incident  beams.
The  program can output the original data from mcml  or  the
convolved   data  in  various  ASCII  formats  as  discussed
subsequently.


10.1   Start conv

     
     To  start  conv on IBM PC compatibles or UNIX machines,
invoke the program conv by typing:
     
     conv

To use conv on Macintoshes, copy or move the program conv to
your  working folder.  Then, double click the conv  icon  to
start it.  If you are using System 7, you may take advantage
of the alias mechanism.


10.2   Main menu of conv

     
     Once  conv  is started, it is in the main menu  of  the
program  after showing some information about  the  program.
In the main menu, the program prompts for a command as:

> Main menu (h for help) =>

To  show all the available command, type "h" and return key.
It  will  show you the following information and prompt  for
the   next  command.   You  only  need  to  show  the   help
information when you forget the commands.

i  = Input filename of mcml output
b  = specify laser Beam
r  = convolution Resolution.
e  = convolution Error.
oo = Output Original data
oc = Output Convolved data
co = Contour output of Original data
cc = Contour output of Convolved data
so = Scanning output of Original data
sc = Scanning output of Convolved data
q  = Quit
* Commands in conv are not case-sensitive

> Main menu (h for help) =>

Each command will be introduced subsequently.


10.3   Command "i" of conv

     
     You have to provide the filename of the mcml output  to
conv.  This can be done by typing "i" and  return key in the
main  menu  prompt, then type in the filename  of  the  mcml
output. For example:

> Main menu (h for help) => i
Input filename of mcml output(or . to quit): example.mco

> Main menu (h for help) =>

The  program returns to the main menu automatically.  If the
file  cannot  be located or opened, the program will  prompt
you  to type in another filename.  You can also type "." and
return  key to quit inputting the filename.  If the file  is
not  the  output  of  mcml, the program  will  quit  to  the
operating system.  You need to start the program again.


10.4   Command "b" of conv

     
     You  need  to  specify the type and parameters  of  the
incident beam.  In version 1.0 of conv, only Gaussian  beams
and  circularly flat (rectangular) beams are supported.   To
enter the incident beam, use command "b".  Then you have  to
choose from "f" for flat beam, "g" for Gaussian beam, or "q"
to  quit  this command.  If you choose either flat  beam  or
Gaussian beam., conv asks the total energy and the radius of
the beam.  For example:

> Main menu (h for help) => b
Beam profile:f=flat, g=Gaussian. q=quit: f
Total energy of the flat beam [J]: 1
Radius of the flat beam [cm]: .1
Total power:        1 J, and radius:      0.1 cm.

> Main menu (h for help) =>

It  returns  to  the main menu automatically.   Although  we
specify  units  of  energy for the incident  beam,  you  can
substitute  units of power throughout the program.   To  get
reliable results, the radius should be much larger than  the
grid  separation  in the r direction of  the  original  mcml
output, and much less than the total covered radius  by  the
grid  system in the r direction of the original mcml output.
As  a  rule  of  thumb, the radius should be  in  the  range
between about 3 times the grid separation in the r direction
and  the  total grid coverage in the r direction  minus  the
maximum  radius  of observation (see Eqs.  7.23  &  7.24  in
Section 7.4).


10.5   Command "r" of conv

This command is used to change the grid separation and the
number of grid elements in the r direction for the
convolution.  Since they take the values of the mcml output
as the default, you do not have to enter this command if you
do not want to change them.  The maximum convolution radius
should not be larger than that of the original mcml output
to get reliable results.  For example:

> Main menu (h for help) => r
Current resolution:     0.01 cm and number of points: 50
Input resolution in r direction [cm]: .02
Input number of points in r direction: 20
Resolution:     0.02 cm and number of points: 20

> Main menu (h for help) =>
     
     Note  that if the number of points is chosen too large,
the  program can exit due to the lack of memory.  This is  a
bug in the current version of conv.


10.6   Command "e" of conv

     
     The integration is computed iteratively.  The iteration
stops  when the difference between the new estimate and  the
old  estimate of the integration is a small part of the  new
estimate.  This small ratio can be controlled by users using
command "e".  It ranges between 0 to 1.  Small values  would
give  better precision but longer computation time and  vice
versa.   Normally, 0.001 to 0.1 is recommended.  The default
value is 0.1.  For example:

> Main menu (h for help) => e
Relative convolution error
Current value is  0.05 (0.001-0.1 recommended): .01
     
     Special attention has to be paid to this command.   The
convolution  results may have weird discontinuities  if  the
allowed  convolution error is too high (see Fig. 7.11),  and
the convolution process may take too long if the convolution
error is too low.  The rule of thumb is that you choose  the
lowest  convolution error that does not make the convolution
too  long to compute.  If the convolution results still have
any  discontinuities which should not be there, you need  to
decrease the convolution error and redo the convolution.


10.7   Command "oo" of conv

     
     After  you input the filename of the mcml output ,  you
can output the original data of the mcml output with various
formats.  One of the formats can be obtained  by the command
"oo".  For example:

> Main menu (h for help) => oo

> Output mcml data (h for help) => h
I   = Input parameters of mcml
3   = reflectance, absorption, and transmittance
AL  = absorption vs layer [-]
Az  = absorption vs z [1/cm]
Arz = absorption vs r & z [1/cm3]
Fz  = fluence vs z [-]
Frz = fluence vs r & z [1/cm2]
Rr  = diffuse reflectance vs radius r [1/cm2]
Ra  = diffuse reflectance vs angle alpha [1/sr]
Rra = diffuse reflectance vs radius and angle [1/(cm2 sr)]
Tr  = transmittance vs radius r [1/cm2]
Ta  = transmittance vs angle alpha [1/sr]
Tra = transmittance vs radius and angle [1/(cm2 sr)]
K   = Keijzer's format
Q   = Quit to main menu
* input filename: example.mco

> Output mcml data (h for help) =>
     
     At   this   point,  you  can  output  various  physical
quantities by inputting the subcommands, which can be listed
by  command "h" as shown above.  After you type the command,
the program will ask you for the output filename.  The exact
physical meanings of these physical quantities can be  found
in  Chapter 4.  The command "i" outputs the input parameters
of mcml to a file.  The command "3" outputs three quantities
to  a  file  including specular reflectance,  total  diffuse
reflectance,    absorption    probability,     and     total
transmittance, which are actually four numbers.  The command
"Al"  outputs the absorption probability as a function layer
to  a  file.  The command "Az" outputs the absorption  as  a
function  of  z  coordinate whose dimension  is  cm-1.   The
command "Arz" outputs the absorption probability density  as
a function of r and z whose dimension is cm-3.  The commands
"Fz"  and "Frz" output the results of the commands "Az"  and
"Arz"  divided by the absorption coefficients.  The  command
"Rr"  outputs  the diffuse reflectance as a  function  of  r
whose  unit  is cm-2.  The command "Ra" outputs the  diffuse
reflectance  as  a  function of  the  exit  angle  a,  whose
dimension  is  sr-1.  The command "Rra" outputs the  diffuse
reflectance as a function of r and a, whose unit is cm-2 sr-
1.   Similarly,  the commands "Tr", "Ta" and "Tra"  are  the
corresponding commands for the transmittance.   The  command
"K"  is used to convert the format of the mcml output to the
format  of Marleen Keijzer's convolution program (in  PASCAL
on  Macintoshes)  which was used by  our  group  before  the
program  conv was written.  This command is only  useful  if
you  have  Marleen Keijzer's program.  The command "q"  will
return the program to the main menu.
     
     For  1D  arrays, the outputs are in two  columns.   The
first  column gives the independent variable, and the second
column  gives  the  physical quantities.  For  example,  the
output of the command "Rr" will have two columns.  The first
column  gives the radius in cm, and the second column  gives
the diffuse reflectance in cm-2.
     
     For  2D arrays, the outputs are in three columns.   The
first  two columns give the first and the second independent
variables,   and  the  third  column  gives   the   physical
quantities.  For example, the command "Arz" will give  three
columns.   The  first  two  columns  give  r  and  z  in  cm
respectively,  and  the third column  gives  the  absorption
probability density in cm-2 sr-1 as a function of r and z.
     
     An example is shown as follows:

> Output mcml data (h for help) => Rr
Enter  output filename with extension .Rr (or  .  to  quit):
example.Rr

> Output mcml data (h for help) =>

This  command  will  output  the diffuse  reflectance  as  a
function of r to the file named "example.Rr".


10.8   Command "oc" of conv

     
     After  you  input the filename of the mcml  output  and
specify  the  incident  photon  beam,  you  can  output  the
convolved data with various formats.  One of the formats  is
writing  data  in columns, which can be obtained  using  the
command "oc".  For example:

> Main menu (h for help) => oc

> Output convolved data (h for help) => h
Arz = absorption vs r & z [J/cm3]
Frz = fluence vs r & z [J/cm2]
Rr  = diffuse reflectance vs radius r [J/cm2]
Rra = diffuse reflectance vs radius and angle [J/(cm2 sr)]
Tr  = transmittance vs radius r [J/cm2]
Tra = transmittance vs radius and angle [J/(cm2 sr)]
Q   = Quit to main menu
* input filename: example.mco

> Output convolved data (h for help) =>
     
     At   this   point,  you  can  output  various  physical
quantities by inputting the subcommands, which can be listed
by  command "h" as shown above.  After you type the command,
the program will ask you for the output filename.  The exact
physical meanings of these physical quantities can be  found
in  Chapters  4  and  7.   The  command  "Arz"  outputs  the
absorption  energy density as a function of r  and  z  whose
dimension is J cm-3.  The command "Frz" outputs the  results
of the command "Arz" divided by the absorption coefficients,
which  is the fluence in J cm-2.  Since we consider  steady-
state   responses   only  in  mcml   and   conv,   you   can
systematically  replace  the  energy  [Joules]  with   power
[Watts] in conv.
     
     The  command "Rr" outputs the diffuse reflectance as  a
function  of  r  whose unit is J cm-2.   The  command  "Rra"
outputs  the diffuse reflectance as a function of r  and  a,
whose unit is J cm-2 sr-1.  Similarly, the commands "Tr" and
"Tra"  are the corresponding commands for the transmittance.
The command "q" will return the program to the main menu.
     
     For  1D  arrays, the outputs are in two  columns.   The
first  column gives the independent variable, and the second
column  gives  the  physical quantities.  For  example,  the
output of the command "Rr" will have two columns.  The first
column  gives the radius in cm, and the second column  gives
the diffuse reflectance in J cm-2.
     
     For  2D arrays, the outputs are in three columns.   The
first  two columns give the first and the second independent
variables  respectively,  and the  third  column  gives  the
physical  quantities.  For example, the command  "Arz"  will
give  three columns.  The first two columns give r and z  in
cm  respectively, and the third column gives the  absorption
energy density in J cm-2 sr-1 as a function of r and z.
     
     An example is shown as follows:

> Output convolved data (h for help) => Rr
Enter  output filename with extension .Rrc (or .  to  quit):
example.Rrc

> Output convolved data (h for help) =>

This  command  will  output  the diffuse  reflectance  as  a
function of r to the file named "example.Rrc".


10.9   Command "co" of conv

     
     After  you  input the filename of the mcml output,  you
can output the original data of the mcml output with various
formats.   One of the formats for 2D arrays is writing  data
in  contour lines.  Every contour line will be given by  two
columns.  This format can be obtained using the command "co"
standing  for  "contours of the original data".   Then,  the
output  file can be imported to some plotting software  such
as KaleidaGraph on Macintoshes, and the contour lines can be
drawn.  For example:

> Main menu (h for help) => co

> Contour output of mcml data (h for help) => h
A = absorption vs r & z [1/cm3]
F = fluence vs r & z [1/cm2]
R = diffuse reflectance vs radius and angle [1/(cm2 sr)]
T = transmittance vs radius and angle [1/(cm2 sr)]
Q   = Quit to main menu
* input filename: example.mco

> Contour output of mcml data (h for help) =>
     
     Since  only  the  2D  arrays need to  be  presented  in
contour lines, there are only four physical quantities.  The
command "A" outputs the absorption probability density as  a
function  of  r and z whose dimension is cm-3.  The  command
"F" outputs the probability fluence as a function of r and z
in   cm-2.    The  commands  "R"  and  "T"  output   diffuse
reflectance and transmittance as a function of r and a in cm-
2 sr-1.
     
     After  you input one of the commands, the program  will
prompt  for  the output filename and the isovalues  for  the
contour output.  The value range of the physical quantity is
shown so that valid isovalues can be provided by users.  You
can  enter as many isovalues as you want.  System memory  is
the  only  thing that limits the number of isovalues.   Stop
entering isovalues by inputting a period ".".  For example:

> Contour output of mcml data (h for help) => A
Enter  output filename with extension .iso (or .  to  quit):
example.iso
The range of the value is 0.156280 to 3294.800000.
Input an isovalue or . to stop: 1000
Input an isovalue or . to stop: 100
Input an isovalue or . to stop: 10
Input an isovalue or . to stop: 1
Input an isovalue or . to stop: .

> Contour output of mcml data (h for help) =>

The  output  file of this example will  have eight  columns,
each  pair of columns describe one contour line.  The values
of the contour lines are 1000, 100, 10, and 1 respectively.


10.10  Command "cc" of conv

     
     After  you  input the filename of the mcml  output  and
specify  the  incident  photon  beam,  you  can  output  the
convolved data with various formats.  One of the formats for
2D  arrays is writing data in contour lines.  Every  contour
line  will  be  given by two columns.  This  format  can  be
obtained  using the command "cc".  The output  file  can  be
imported to some plotting software such as KaleidaGraph, and
the contour lines can be drawn.  For example:

> Main menu (h for help) => cc

> Contour output of convolved data (h for help) => h
A = absorption vs r & z [J/cm3]
F = fluence vs r & z [J/cm2]
R = diffuse reflectance vs radius and angle [J/(cm2 sr)]
T = transmittance vs radius and angle [J/(cm2 sr)]
Q   = Quit to main menu
* input filename: example.mco

> Contour output of convolved data (h for help) =>
     
     Since  only  the  2D  arrays need to  be  presented  in
contour lines, there are only four physical quantities.  The
command  "A"  outputs  the absorption energy  density  as  a
function of r and z whose dimension is J cm-3.  The  command
"F"  outputs the fluence as a function of r and z in J cm-2.
The  commands  "R"  and "T" output diffuse  reflectance  and
transmittance  as  a function of r and  a  in  J  cm-2  sr-1
respectively.
     
     After  you input one of the commands, the program  will
prompt  for  the output filename and the isovalues  for  the
contour output.  The value range of the physical quantity is
shown so that valid isovalues can be provided by users.  You
can  enter as many isovalues as you want.  System memory  is
the  only  thing that limits the number of isovalues.   Stop
entering isovalues by inputting a period ".".  For example:

> Contour output of convolved data (h for help) => A
Enter  output filename with extension .iso (or .  to  quit):
exampleAc.iso
The range of the value is 0.048200 to 95.624939.
Input an isovalue or . to stop: 80
Input an isovalue or . to stop: 8
Input an isovalue or . to stop: 0.8
Input an isovalue or . to stop: .

> Contour output of convolved data (h for help) =>

The output file of this example will  have six columns, each
pair  of  columns describe one contour line.  The values  of
the contour lines are 80, 8, and 0.8 respectively.


10.11  Command "so" of conv

     
     After  you  input the filename of the mcml output,  you
can output the original data of the mcml output with various
formats.   One of the formats for 2D arrays is writing  data
in  two  columns,  where the two columns give  the  physical
quantity  as a function of one of two independent variables.
The other variable is fixed at a certain value which can  be
chosen by users.  This format, we call scanning output,  can
be  obtained using the command "so".  The output file can be
imported  to  some  plotting software such as  KaleidaGraph.
For example:

> Main menu (h for help) => so

> Scans of mcml data (h for help) => h
Ar = absorption vs r @ fixed z [1/cm3]
Az = absorption vs z @ fixed r [1/cm3]
Fr = fluence vs r @ fixed z [1/cm2]
Fz = fluence vs z @ fixed r [1/cm2]
Rr = diffuse reflectance vs r @ fixed angle [1/(cm2 sr)]
Ra = diffuse reflectance vs angle @ fixed r [1/(cm2 sr)]
Tr = transmittance vs r @ fixed angle [1/(cm2 sr)]
Ta = transmittance vs angle @ fixed r [1/(cm2 sr)]
Q  = quit
* input filename: example.mco

> Scans of mcml data (h for help) =>
     
     The  command  "Ar"  outputs the absorption  probability
density as a function of r for a fixed z, whose dimension is
cm-3.   The  command "Az" outputs the absorption probability
density as a function of z for a fixed r, whose dimension is
cm-3.  The command "Fr" outputs the probability fluence as a
function  of  r  for a fixed z in cm-2.   The  command  "Fz"
outputs  the probability fluence as a function of  z  for  a
fixed  r  in  cm-2.   The command "Rr" outputs  the  diffuse
reflectance  as a function of r for a fixed a  in  cm-2sr-1.
The  command  "Ra"  outputs  the diffuse  reflectance  as  a
function of a for a fixed r in cm-2sr-1.  The commands  "Tr"
and  "Ta" output the transmittance in the same format as for
the  diffuse  reflectance.  The command "q" returns  to  the
main menu.
     
     After  you input one of the commands, the program  will
prompt  for  the output filename and the grid index  to  the
value  of  the  fixed variable.  If you want to  abort  this
output,  you  can input a period "." as the  filename.   For
example:

> Scans of mcml data (h for help) => Ar
Enter  output filename with extension .Ars (or .  to  quit):
example.Ars
z grid separation is 0.01       cm.
Input fixed z index (0 - 39): 0

> Scans of mcml data (h for help) =>
     
     This command outputs the absorption as a function of  r
for a fixed z.  The program shows that the z grid separation
is  0.01 cm.  The number of grid elements in the z direction
is  40.   The grid index in the z direction is in the  range
from  0 to 39.  The command will generate two columns.   The
first column is r, and the second is the absorption.


10.12  Command "sc" of conv

     
     After  you  input the filename of the mcml  output  and
specify  the  incident  photon  beam,  you  can  output  the
convolved data with various formats.  One of the formats for
2D  arrays  is  writing data in two columns, where  the  two
columns give the physical quantity as a function of  one  of
two independent variables.  The other variable is fixed at a
certain value which can be chosen by users.  This format, we
call  scanning  output, can be obtained  using  the  command
"sc".   Then,  the  output  file can  be  imported  to  some
plotting software such as KaleidaGraph.  For example:

> Main menu (h for help) => sc

> Scans of convolved data (h for help) => h
Ar = absorption vs r @ fixed z [J/cm3]
Az = absorption vs z @ fixed r [J/cm3]
Fr = fluence vs r @ fixed z [J/cm2]
Fz = fluence vs z @ fixed r [J/cm2]
Rr = diffuse reflectance vs r @ fixed angle [J/(cm2 sr)]
Ra = diffuse reflectance vs angle @ fixed r [J/(cm2 sr)]
Tr = transmittance vs r @ fixed angle [J/(cm2 sr)]
Ta = transmittance vs angle @ fixed r [J/(cm2 sr)]
Q  = quit
* input filename: example.mco

> Scans of convolved data (h for help) =>
     
     The  command "Ar" outputs the absorption energy density
as a function of r for a fixed z, whose dimension is J cm-3.
The command "Az" outputs the absorption energy density as  a
function of z for a fixed r, whose dimension is J cm-3.  The
command  "Fr" outputs the fluence as a function of r  for  a
fixed z in J cm-2.  The command "Fz" outputs the fluence  as
a  function of z for a fixed r in J cm-2.  The command  "Rr"
outputs  the diffuse reflectance as a function of  r  for  a
fixed  a  in  J  cm-2 sr-1.  The command  "Ra"  outputs  the
diffuse reflectance as a function of a for a fixed r in J cm-
2 sr-1.  The commands "Tr" and "Ta" output the transmittance
in  the  same  format as for the diffuse  reflectance.   The
command "q" returns to the main menu.
     
     After  you input one of the commands, the program  will
prompt  for  the output filename and the grid index  to  the
value  of  the  fixed variable.  If you want to  abort  this
output,  you  can input a period "." as the  filename.   For
example:

> Scans of convolved data (h for help) => Ar
Enter  output filename with extension .Arsc (or . to  quit):
example.Arsc
z grid separation is 0.01       cm.
Input fixed z index (0 - 39): 0

> Scans of convolved data (h for help) =>
     
     This command outputs the absorption as a function of  r
for a fixed z.  The program shows that the z grid separation
is  0.01 cm.  The number of grids in the z direction is  40.
The grid index in the z direction is in the range from 0  to
39.   The  command  will generate two  columns.   The  first
column is r, and the second is the absorption.


10.13  Command "q" of conv

     
     If  you  want to quit the program conv, use the command
"q"  in  the  main menu.  The program will ask  you  if  you
really mean to quit.  You can answer yes or no.  The program
will quit if the answer is "y".  Otherwise, the program will
return to the main menu.  For example:

> Main menu (h for help) => q
Do you really want to quit conv (y/n): n

> Main menu (h for help) => q
Do you really want to quit conv (y/n): y


10.14  Bugs of conv

     
     The  convolution results may have weird discontinuities
if  the  allowed  convolution error is  too  high,  and  the
convolution  process may take too long  if  the  convolution
error is too low.  We do not have a good way to predict  the
best  convolution error yet.  The rule of thumb is that  you
choose  the lowest convolution error that does not make  the
convolution too long to compute.  If the convolution results
still  have any discontinuities which should not  be  there,
you  need  to  decrease the convolution error and  redo  the
convolution.
     
     As  we  discussed  in Section 7.5, the  radius  of  the
incident  beam has to be in the right range to get  reliable
convolution  integration due to the spatial  resolution  and
the  range  of grid system.  As a rule of thumb, the  radius
should  be  in  the  range between about 3  times  the  grid
separation in the r direction and the total grid coverage in
the r direction minus the maximum radius of observation (see
Eqs. 7.23 & 7.24 in Section 7.4).
     
     If  the  number of points in the r direction is  chosen
too  large in the command "r", the program can exit  due  to
the lack of memory.
                              
    Appendix G.  Where to Get the Programs mcml and conv
     
     We  will eventually set up a bulletin board of our  own
so that you can download the software over the network.  For
now, you can contact Lihong Wang, or Steven L. Jacques using
the following information to get the software.
                              
                     Lihong Wang, Ph. D.
           Laser Biology Research Laboratory - 017
      University of Texas M. D. Anderson Cancer Center
                     1515 Holcombe Blvd.
                    Houston, Texas 77030
                     Fax: (713)792-3995
             email: lihong@odin.mda.uth.tmc.edu
                              
                             or
                  Steven L. Jacques, Ph. D.
           Laser Biology Research Laboratory - 017
      University of Texas M. D. Anderson Cancer Center
                     1515 Holcombe Blvd.
                    Houston, Texas 77030
                     Fax: (713)792-3995
               email: slj@odin.mda.uth.tmc.edu


Make  sure that you tell us the specific machines (including
brand and model) you will use for the simulation, so that we
can  compile the code correctly for you.  If you use IBM  PC
compatibles, please also tell us whether you use a math  co-
processor or not.

August 20, 1992

