Tutorial: Use of VTS Monte Carlo 1.0

GOAL: To learn how to execute and view results from Monte Carlo simulations and various other forward solvers.

I. Plots of Reflectance and Fluence across solution models

  1. Create a folder on your Desktop called "LabExercises".
  2. Select the "Monte Carlo Solver Panel".
  3. Click the "Download Prototype Input Files" , save the zip file to folder LabExercises and extract all (right click the zip file and select "extract all".
  4. In the Input File Specification, click the "Load Input File" button. Go to the LabExercises folder and select the file one_layer_ROfRho_FluenceOfRhoAndZ.xml. This is a Monte Carlo simulation input file that specifies a Discrete Absorption Weighting (DAW) simulation to produce reflectance as a function of source-detector (ρ) separation, R(ρ), and fluence as a function of ρ and z using 10000 photons. For a full description of the input file settings see https://github.com/VirtualPhotonics/VTS/wiki/MCCL-Capabilities-And-Implementation.
  5. Input notes:
    1. Three layers are defined in the input file: air above, tissue, and air below. This is shown in the scrollbar box under "Tissue Input" on the panel. The optical properties of the tissue are set to μa = 0.01mm-1, μ's = 1mm-1, g = 0.8 and n = 1.4. These values can be changed by entering new values in the scrollbar box.
    2. While this simulation is executed in a full 3D geometry the results are binned using cylindrical coordinates since the detector R(ρ) is designated. There are 101 equispaced ρ in[0-10]mm and z in [0-10]mm bins specified in this input file.
    3. If there are errors in the specified input, the simulation will not execute and a message will be output to the text box indicating the source of the error.
  6. Click the "Run Simulation" button (this may take a few minutes for 10000 photons).
  7. View the reflectance plot as a function of ρ. Change the Y Axis Spacing to Log10. Note the time required for execution of the simulation in the text box. The cause for the apparent increase in reflectance for the last ρ position is that all photons exiting at positions beyond the last ρ position are tallied in the final bin.
  8. Click on the "Map View" tab and view the associated Fluence as a function of radial (ρ) and axial (z) positions. This plot mirrors the ρ,z results about ρ = 0. Explore different visualizations of the data by using the "Log10" vs. "Linear" radio buttons, changing "Min" and "Max" settings, and colormap type.
  9. Click back to the "Plot View" tab and make sure "Hold On" is checked.
  10. Select the "Forward Solver/Analysis Panel" and select "Scaled Monte Carlo - NURBS" from the pull-down menu.
  11. Select the R(ρ) radio button and "Detector Positions" Begin=0.05 mm, End=9.95 mm, Number=100.
  12. Make sure the optical properties match those specified in the Monte Carlo solution.
  13. Click "Plot Reflectance".

II. Download Monte Carlo CommandLine Application from CodePlex

  1. Go to our GitHub site: https://github.com/VirtualPhotonics
  2. Click on "Downloads" to download software and then extract all files.
  3. Sample input files are bundled with the software. The Simulation Input file newinfile_one_layer_ROfRho_FluenceOfRhoAndZ.txt specifies a simulation using a collimated point source incident upon a homogeneous, 100mm thick slab of tissue with optical properties: μa = 0.01mm-1, μ's = 1mm-1, g = 0.8 and n = 1.4. The number of photons launched, N, is set to 100.
  4. Execute the simulation by bringing up a command line window and "cd" to the download folder. Type "mc infile=newinfile_one_layer_ROfRho_Fluence.txt" at the command line prompt. Note that other options to "mc" are listed by entering "mc help". For a full list of command line options, see the "MCCL Examples" link on the GitHub page (https://github.com/VirtualPhotonics/VTS/wiki/MCCL-Examples).
  5. The results of the simulation are in newly created folder "one_layer_ROfRho_FluenceOfRhoAndZ".
  6. To view plots of the results, bring up MATLAB (clicking on the file "load_results_script.m" will do this). Enter "load_results_script" at the MATLAB prompt. This should show two plots, one of R(ρ) and one of Fluence(ρ,z).
  7. To edit the input use JSON online editor (https://jsoneditoronline.org/). Try changing N to 1000 and re-execute the simulation.
  8. To edit the MATLAB script, edit the file "load_results_script.m" within MATLAB by clicking on it in the left hand side bar of MATLAB. Note the three fields: 1) "datanames" is folder where the results reside, 2) "outdir" is the path to the results folder, and 3) the list of show.RDiffuse, etc. sets which results are plotted (set to 1) or not (set to 0). Note that if you execute an input file that does not specify, for example, Fluence, it will not be plotted.