MCCL Post Processor

Monte Carlo Post-Processor (MCPP)

The Monte Carlo Post-Processor (MCPP) comes bundled with the Monte Carlo Command Line Application (MCCL) download (see Downloads link on right hand panel). The MCPP is used to post-process a baseline MCCL simulation and generate results quickly without running another simulation. Reflected and/or transmitted photons can be saved, each to their own database. Pertinent information for each photon from the baseline simulation is stored in a database then retrieved by the MCPP to provide detector results. The MCPP is useful:

1. when you would like to change detector bin sizes and regenerate the results,
2. to generate results for various mua values in the tissue using Beer's law, and
3. to run perturbation Monte Carlo.

More information about these items is described below. The MCCL download includes MCPP sample input files, infile_PostProcessor_xxx.txt.

General MCPP Description

The main advantage of using MCPP is to generate detector results quickly once an initial baseline simulation has been executed. If the source and tissue definitions are fixed in your model, then a large number of photons can be simulated and pertinent information for each photon (e.g. path lengths and number of collisions within each tissue region) can be stored in a database. Then the MCPP can read the database and generate detector results very efficiently at a computational cost much less than the time of the baseline simulation.

This would be useful, for example, when you'd like to generate detector results and are unsure where to place your detectors spatially, angularly or temporally. After running the baseline simulation, you can run the MCPP and specify detector inputs with various spatial, angular or temporal bin sizes and determine which specifications provide the smallest error.

To generate the database:

1. Follow the directions to download the application and unzip for Linux, Mac or Windows
2. The steps that are described next pertain to specifying a reflectance database. Similar steps can be performed to add in or substitute a transmittance database.
3. Copy the sample MCCL infile "infile_pMC_one_layer_ROfRho_DAW.txt" to a file name of your choice. This will save your edits in case you happen to run geninfiles again and overwrite the file. This infile provides a template of how to generate the baseline database.
4. Edit the new infile. In the "Options" section of the infile, under "Databases", a "DiffuseReflectance" database is shown. The "DiffuseReflectance" option is specified if diffuse reflectance type detectors are needed (for diffuse transmittance detectors "DiffuseTransmittance" would be added in or substituted, for specular reflectance "SpecularReflectance" would be used). Add any reflectance detectors as you would normally (see MCCL:Editing infiles on right side panel for more information).
5. Run MCCL with this infile. Type on windows

mc infile=infile_pMC_one_layer_ROfRho_DAW.txt

on Linux and Mac

./mc infile=infile_pMC_one_layer_ROfRho_DAW.txt

A folder is created named "pMC_one_layer_ROfRho_DAW" and within this folder a database "DiffuseReflectanceDatabase" and information file "DiffuseReflectanceDatabase.txt" are created.

To post-process the information in the database:

1. Run the option "geninfiles" using the MCPP, e.g. type on windows:

mc_post geninfiles

on linux or OSX, set permissions on the executable first

chmod 755 mc_post
./mc_post geninfiles

This will generate sample MCPP infiles.

2. Copy the sample infile "infile_PostProcessor_pMC_ROfRhoROfRhoAndTime.txt" to a name of your choice. Again, in case you happen to run geninfiles again and overwrite the file. Edit the new infile and specify the "InputFolder" to be "pMC_one_layer_ROfRho_DAW" and "DatabaseSimulationInputFilename" to be "pMC_one_layer_ROfRho_DAW" which specifies the folder the database from MCCL is stored. You can also edit the "OutputName" to specify the name of the folder the output results will be place. Also edit the "DetectorInputs" section specifying the detectors of interest.

3. Run MCCP with this new infile. Type on windows:

mc_post infile=infile_PostProcessor_pMC_ROfRhoROfRhoAndTime.txt

on linux or OSX

./mc_post infile=infile_PostProcessor_pMC_ROfRhoROfRhoAndTime.txt

This will create a folder name using the "OutputName". I used the default name "PostProcessor_pMC_ROfRhoROfRhoAndTime".

4. Edit the Matlab script "load_results_script.m" and modify "datanames" to be "PostProcessor_pMC_ROfRhoROfRhoAndTime" and run it using Matlab. A plot of your results should be displayed.

Using MCPP to generate detector results for multi-region tissues with varying mua values

One of the more powerful capabilities of the MCPP is to provide detector results for tissue definitions with varying mua values. To run the baseline simulation the infile "Options" specification of "AbsorptionWeightingType" must be set to "Continuous". This will define photon propagation path lengths to have a mean free path based on mus rather than mut. Then Beer's law can be used to determine the final photon weight (ref: Hayakawa et al., J. Opt. Soc. Am A, 31(2), p. 301-311, 2014).

To generate the database:

1. In the MCCL infile set in "Options" "AbsorptionWeightingType" to be "Continuous" and set "Databases" to be "pMCDiffuseReflectance".
2. Run the MCCL with this infile. This will create a folder according to the infile "OutputName" specification. Within this folder there will be two database files, "DiffuseReflectanceDatabase" and "CollisionInfoDatabase" and their associated information "*.txt" files.

To post-process the information in the database:

1. Use the sample MCPP infile "infile_PostProcessor_pMC_ROfRhoROfRhoAndTime.txt" as a template. Edit the "InputFolder" and "DatabaseSimulationInputFilename" to match the MCCL output folder.
2. Edit the "DetectorInputs" and specify the "PerturbedOps" for the tissue (e.g. the second set of optical properties listed if the system is defined as air-tissue-air) to identical to the baseline MCCL infile except modify "Mua" to the value of interest. Within this same section specify "PerturbedRegionsIndices" to the tissue regions that have the modified "Mua" values. The "PerturbedRegionsIndices" is based on a 0 index count. For example, if the tissue is defined as air-tissue-air, the tissue region index is 1. Note that if a multi-region tissue is specified, any of the tissue regions can have varying mua values.
3. Similar to that described above, edit the Matlab script "load_results_script.m" and modify "datanames" and run it using Matlab. A plot of your results should be displayed.

Using MCPP for perturbation Monte Carlo (pMC) results

Pertubation Monte Carlo reads the baseline MCCL database and provides detector results for tissue definitions with slightly different mua and mus values (ref: Hayakawa et al, Optics Letters 26(17), p.1335-7, 2001). It can be applied to baseline simulations using discrete or continuous absorption weighting (when continuous absorption weighting and mua only perturbations are specified, it resorts to the method described in the previous section). It is a perturbative method so it works best when the mua and/or mus values are slightly different from the baseline values. Using a single set of random walks to generate detector results for various mua and mus perturbations will effectively capture the change to the detector response due to the correlation in the results. It is much more accurate in capturing the change than when an independent MCCL simulation is used to generate the perturbed system response because the statistical noise between the two simulations is not introduced.

To generate the database:

1. In the MCCL infile set in "Options" "AbsorptionWeightingType" to be "Continuous" or "Discrete" and set "Databases" to be "pMCDiffuseReflectance".
2. Run the MCCL with this infile.

To post-process the information in the database:

1. Use the sample MCPP infile "infile_PostProcessor_pMC_ROfRhoROfRhoAndTime.txt" as a template. Edit it as described in the previous section. The "PerturbedOps" can include perturbations to "Mua" and "Mus".
2. Similar to that described above, edit the Matlab script "load_results_script.m" and modify "datanames" and run it using Matlab. A plot of your results should be displayed.