This project has moved. For the latest updates, please go here.

Editing Monte Carlo Command Line infiles

The Monte Carlo Command Line Application download (see Downloads tab above) comes bundled with sample input files, infile_xxx.txt, where 'xxx' describes the tissue and detector(s) specified (the source is a collimated point source). These files might not contain the particular source, tissue and detector(s) combination you are interested in, so this page describes how to edit an txt infile for your particular need.

Editing the txt file

Now say you would like an infile that specifies a collimated point source, 2 layer tissue and a reflectance detector that is a function of source-detector separation (rho). The download includes a sample file called infile_one_layer_all_detectors.txt. Lets start with that file because it has the detector already specified and we can easily modify the one layer tissue to two layers.

Open the file with any text editor

Deleting extra detectors

The various detectors are specified in the 'DetectorInputs' section toward the end of the file. Each detector is included within two curly brackets '{' and '}'. The first detector input is for 'AOfRhoAndZ'. At the top of this detector specification, there is a 'Rho' and a 'Z' section defining the range of these independent variables. To delete this detector, delete all text starting with the '{' before the 'Rho' line, and up to and including the final '},' after 'IsNotImplementedYet' : false }'.

Editing the detector bin specifications

To specify the rho bins, The values listed to the right indicate a 'Count' of 101, 'Start' of 0 and 'Stop' of 10. The 'Start' and 'Stop' are in units of mm. Note that these selections specify 100 contiguous rho bins (1 less than 'Count') of size 0.1 mm, with the first bin set to [0, 0.1]mm, second [0.1,0.2]mm, up to the last bin [9.9, 10]mm. Edit these values according to your problem specifications.

Adding a tissue layer

The tissue is specified within the 'TissueInput' section and 'Regions' subsection. You will see 3 'Regions' because this input specifies a one layer tissue with air above and below, i.e. a 3-layer system. In the first 'layer', you will see that its 'ZRange' goes from -INF (negative infinity) to 0 and that it has optical properties of air. Similarly, for the last 'layer', the 'ZRange' goes from 100mm to INF (positive infinity) with optical properties of air. The second 'layer' specifies a tissue layer that is 100mm thick and infinite in the x- and y- axis directions.

We would like a 4-layer system with 2 layers of tissue. So copy the second tissue 'TissueRegionType' including the surrounding '{' '},'. Then paste this copy below it.

Edit the 2nd and 3nd layers' 'RegionOP' (optical properties) and 'ZRange' for the two tissue layers making sure that the 'Stop' value of each layer matches the 'Start' value of the next layer. No editing is required for the 1st and 4th air layers. Note that the default optical properties for the tissue layers are g=0.8, mua=0.01/mm, mus=5/mm, mus'=1/mm and n=1.4.

Specifying the output folder

As a final step, edit the 'OutputName' from 'one_layer_all_detectors' to 'two_layer_ROfRhoAndTime'. This 'OutputName' is used to specify the output folder where the results will reside.

Executing the edited infile

Save the file to say 'infile_two_layer_ROfRhoAndTime.txt' and keep 'N' (the number of photons to launch) set to 100 for now. Open a command line window, 'cd' to the download folder and try executing it with

mc.exe infile=infile_two_layer_ROfRhoAndTime.txt

Refer to Monte Carlo Command line Documentation for other options. We have some validation software in place that will hopefully catch if incorrect inputs are specified.

Viewing the results using matlab

After the simulation has executed successfully, you can view the results using matlab. Edit the file 'load_results_script.m' that is part of the download, and modify 'datanames' to be the name of the output folder, 'two_layer_ROfRhoAndTime'. Execute this file in matlab and a 2D plot of reflectance as a function of rho and time will be shown. Note that these are the results of 100 photons.

So increase N and run again. The choice of an appropriate 'N' is dependent on the optical properties and thickness of the tissue, and the size of the bins (in this case rho and time). You can check the relative error (standard deviation divided by the mean) of the bin results and increase N so that the relative error is less than 0.05 (MCNP manual recommendation). To do this, set 'Options', 'TallySecondMoment' to true in the input file. Then edit the matlab file 'load_results_script.m' to display 'ROfRhoAndTime.Stdev./ROfRhoAndTime.Mean'.

Editing Monte Carlo Command Line XML infiles (obsolete)

The Monte Carlo Command Line Application download (see Downloads tab above) comes bundled with sample input files, infile_xxx.xml, where 'xxx' describes the tissue and detector(s) specified (the source is a collimated point source). These files might not contain the particular source, tissue and detector(s) combination you are interested in, so this page describes how to edit an xml infile for your particular need.

Useful Tool

First, download a tool that eases the editing process on Windows, XML Notepad 2007.

Editing the xml file

Now say you would like an infile that specifies a collimated point source, 2 layer tissue and a reflectance detector that is a function of source-detector separation (rho) and time. The download includes a sample file called infile_one_layer_all_detectors.xml. Lets start with that file because it has the detector already specified and we can easily modify the one layer tissue to two layers.

Open the file with XML Notepad

OpenXML.JPG

Deleting extra detectors

Click on the '+' sign to the left of 'DetectorInputs'. This expands the folder of detector inputs and shows all detectors specified. Click on the '+' sign to the left of the first subfolder 'a:anyType'

DetectorViewing.JPG

This shows the total diffuse reflectance detector 'RDiffuse'. Click on the '-' sign to the left to close this folder and continue down the list until you find the detector with name 'ROfRhoAndTimeDetectorInput'

DetectorROfRhoAndTime.JPG

Since this is the only detector we are interested in specifying, delete all other detector specifications by selecting the folder ('a:anyType' will be highlighted in blue) and then selecting 'Edit->Delete'

OnlyDetectorROfRhoAndTime.JPG

Editing the detector bin specifications

To specify the rho bins, expand the 'Rho' folder and then the 'Count', 'Start' and 'Stop' subfolders

RhoBins.JPG

The values listed to the right indicate a 'Count' of 101, 'Start' of 0 and 'Stop' of 10. The 'Start' and 'Stop' are in units of mm. Note that these selections specify 100 contiguous rho bins (1 less than 'Count') of size 0.1 mm, with the first bin set to [0, 0.1]mm, second [0.1,0.2]mm, up to the last bin [9.9, 10]mm. Edit these values according to your problem specifications. In a similar fashion, specify the Time bins under the 'Time' folder (the units of time are ns).  Note that these subfolders (and all subfolders in the infile) have to remain in the order in which they appear which is alphabetically.  Rearrangement of the subfolders will result in an infile that will produce erroneous results.

Adding a tissue layer

When the detector input updates are complete, collapse the folder 'DetectorInputs' and expand the 'TissueInput' folder and 'Regions' subfolder. You will see 3 subfolders 'a:anyType;' because this input specifies a one layer tissue with air above and below, i.e. a 3-layer system. If you expand the first 'layer', you will see that its 'ZRange' goes from -INF (negative infinity) to 0 and that it has optical properties of air. Similarly, for the last 'layer', the 'ZRange' goes from 100mm to INF (positive infinity) with optical properties of air. The second 'layer' specifies a tissue layer that is 100mm thick and infinite in the x- and y- axis directions.

We would like a 4-layer system with 2 layers of tissue. So click on the second tissue folder ('a:anyType' will be highlighted in blue) and select Edit->Copy. Then select the 'Regions' folder and select Edit->Paste. This will paste the layer onto the bottom of the 'Regions' list so that now there are 4 subfolders under 'Regions'. But it is our second tissue layer so we would like it to be between the original 2nd and 3rd folders. You can move the last folder to the 3rd position by selecting it and while holding down the right click, moving it to the correct position within the list (you will see a faint blue bar indicating the potential placement).

MoveAppendedLayer.JPG

Proceed to edit the 2nd and 3nd subfolders' 'RegionOP' (optical properties) and 'ZRange' for the two tissue layers similar to how the Rho bins were edited. No editing is required for the 1st and 4th air layers. Note that the default optical properties for the tissue layers are g=0.8, mua=0.01/mm, mus=5/mm, mus'=1/mm and n=1.4. Make sure that for each layer, the 'ZRange' 'Stop' value agrees with the 'ZRange' 'Start' value of the next region.

Specifying the output folder

As a final step, edit the 'OutputName' from 'one_layer_all_detectors' to 'two_layer_ROfRhoAndTime'. This 'OutputName' is used to specify the output folder where the results will reside.

Executing the edited infile

Save the file to say 'infile_two_layer_ROfRhoAndTime.xml' and keep 'N' (the number of photons to launch) set to 100 for now. Open a command line window, 'cd' to the download folder and try executing it with

mc.exe infile=infile_two_layer_ROfRhoAndTime.xml

Refer to Monte Carlo Command line Documentation for other options. We have some validation software in place that will hopefully catch if incorrect inputs are specified.

Viewing the results using matlab

After the simulation has executed successfully, you can view the results using matlab. Edit the file 'load_results_script.m' that is part of the download, and modify 'datanames' to be the name of the output folder, 'two_layer_ROfRhoAndTime'. Execute this file in matlab and a 2D plot of reflectance as a function of rho and time will be shown. Note that these are the results of 100 photons.

So increase N and run again. The choice of an appropriate 'N' is dependent on the optical properties and thickness of the tissue, and the size of the bins (in this case rho and time). You can check the relative error (standard deviation divided by the mean) of the bin results and increase N so that the relative error is less than 0.05 (MCNP manual recommendation). To do this, set 'Options', 'TallySecondMoment' to true in the input file. Then edit the matlab file 'load_results_script.m' to display 'ROfRhoAndTime.Stdev./ROfRhoAndTime.Mean'.

Resulting infile

The resulting infile specifying a two-layer tissue (top layer 1mm thick, bottom layer 99mm thick and default optical properties) with and air layer above and below, and R(rho,time) detection is infile_two_layer_ROfRhoAndTime.xml.

Last edited Aug 19, 2015 at 12:35 AM by hayakawa, version 14

Comments

dcuccia Apr 26, 2012 at 3:24 AM 
Nice!