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