Showing revision 2

Descriptions of the MMC example simulations

1. validation - Validation of MMCM in a homogeneous cubic domain
2. meshtest - Validation of MMCM in a heterogeneous domain - a sphere inside a cube
3. onecube - Visual debugging of photon migration in a simple mesh
4. dcs - Validation of MMCM simulation of DCS auto-correlation measurements
5. statnoise: Fluence variation vs photon numbers (Experimental)
6. Reference:
Under the example sub-folder of MMC binary or source packages, you can find a number of examples to validate, test, or demonstrate the functionalities of MMC. The description of each example can be found below.

The examples contained in each subfolders are explained below:

 examples/
  |-validation - homogeneous cubic domain 60x60x60, i.e. Fig. 2 in Fang2010
  |-meshtest   - 10mm sphere embedded in the cubic domain, Fig. 3 in Fang2010
  |-mcxsph     - scripts to run MCX for the above two cases
  |-onecube    - debugging flag show case 1, simple mesh without reflection
  |-reftest    - debugging flag show case 2, simple mesh with reflection
  |-rngtest    - random number generator test
  |-dcs        - validation of momentum transfer in DCS simulation
  |-statnoise  - test statistical noise against launched photon numbers
  |-misctest   - other misc. tests

1. validation - Validation of MMCM in a homogeneous cubic domain

Introduction

In this example, we validate the MMCM algorithm using a homogeneous cubic domain. This simulation generates the results shown in Fig. 2 in the paper.

The cubic domain has a dimension of 60x60x60 mm with optical properties mua=0.001, mus=1, n=1.0 and g=0.01. The analytical solution can be computed by the cwdiffusion (for CW solution) and tddiffusion (for time-domain solutions) functions in the package of Monte Carlo eXtreme (MCX) under the mcx/utils directory.

Steps

1. In order to run this example, you need to first download and install the svn version of iso2mesh from

 svn checkout --username anonymous_user https://orbit.nmr.mgh.harvard.edu/svn/iso2mesh/trunk/iso2mesh iso2mesh

the password is anonymous_user

2. Start matlab, run createmesh to create all mesh files. Matlab will print a value for variable eid. This value indicates the initial element ID in the mesh that encloses the source. You need to manually set this number as the second integer on the 7-th line in cube.inp input file.

3. Run the simulation bash script run_test.sh, this will run 30000000 photons with the specified mesh.

4. To produce Fig. 2, you need to run MCX simulations. You have to download MCX package from

 svn checkout --username anonymous_user https://orbit.nmr.mgh.harvard.edu/svn/mcextreme/mcextreme_cuda/trunk/ mcx

using the password "anonymous_user". You can also download the pre-compiled binary package from http://mcx.sf.net/cgi-bin/index.cgi?Download

5. Assuming you have compiled and installed MCX, you can run MCX simulation by

5.1 go to mmc/examples/mcxsph run createmcxbin from matlab

5.2 open benchbox.sh, edit the thread number (-t) and thread block size (-T) based on the compute capability of your card. For 8800GT/9800GT, the -T number can not exceed 128; for 280/285/295, -T can not be more than 256; for 470, -T can not be more than 576

5.3 run benchbox.sh to generate the MCX output box.mc2

6. When all simulations are down, you start matlab again, and run plotcuberes to generate the plots.

2. meshtest - Validation of MMCM in a heterogeneous domain - a sphere inside a cube

Introduction

In this example, we validate MMCM algorithm using a sphere object in a homogeneous cubic background. This simulation generates the results shown in Fig. 3 in the paper.

The cubic domain has a dimension of 60x60x60 mm with optical properties mua=0.002, mus=1, n=1.37 and g=0.01. A sphere is centered at [30 30 30]mm with a radius of 10mm. The optical properties of the sphere is mua=0.05, mus=5, n=1.37 and g=0.9. The analytical solution, approximated by a sphere inside a infinite slab, can be computed by the sphdiffusionslab function in mmc/matlab/ directory (this has already been done, the result for plane y=30 is saved in the sphdiffsemiinf.mat file).

To validate MMCM, we generate an FE-mesh for the sphere and the cube. Three meshes are tested: sph1: a coarse FE mesh with only 10,000 nodes, sph2: a uniform dense FE mesh with 60000 nodes, and sph3: a mesh with higher density around the sphere surface and near the source. The case sph2 and sph3 correspond to "MMCM Mesh 1" and "MMCM Mesh 2" in the paper (Table 1), respectively.

Steps

1. First, you need to create the 3 meshes to run this example. You need to first download and install the svn version of iso2mesh from

 svn checkout --username anonymous_user https://orbit.nmr.mgh.harvard.edu/svn/iso2mesh/trunk/iso2mesh iso2mesh

the password is anonymous_user

2. Start matlab, run createmesh to create all mesh files

3. Open initial_elem.txt, and type the integer in each line to replace the second integer at the 7-th line of sph{1,2,3}.inp (this sets the initial element ID, because the mesh generator may generate a different mesh on your system, you have to update this manually)

4. run the simulation bash script run_test.sh

5. when all 3 simulations are complete, you start matlab again, and run plotmmcsph to generate the plots.

3. onecube - Visual debugging of photon migration in a simple mesh

Introduction

In this example, we run photon migration in a toy-problem to show the basic steps and behaviors of the simulation code. The mesh used in this case is a simple cube, splitted into 6 tetrahedra. The edge length of the cube is 10mm. A total of 20 photons are simulated starting from a source position [2,8,0] along an incident vector [0 0 1]. We run the simulation and print out the moving trajectories of the photon, and the exit and accumulation sites. Using a matlab script, one can visualize the photon moving from the output of the simulation.

Steps

1. The mesh files for this example has already been generated. if you want to regenerate the mesh files, please open matlab or octave and run "createmesh"

2. Run the simulation by typing

  ./run_test.sh

3. Start matlab, run "plotmmcdebug" to see the photon trajectory plot

4. dcs - Validation of MMCM simulation of DCS auto-correlation measurements

  • Author: Stefan Carp (carp <at> nmr.mgh.harvard.edu or carp <at> alum.mit.edu)
  • Date: October 18, 2011

Monte Carlo simulations of light propagation are generally used to estimate fluence distributions, or the intensity of diffusely reflected light from a turbid medium. By storing the history of scattering angles on a per-photon basis (momentum transfer) in addition to the photon pathlenghts it is possible to derive the expected electric field auto-correlation on the surface of the medium for a given distribution of scatterer dynamics in the medium.

Diffuse correlation spectroscopy (DCS) as Diffusing Wave Spectroscopy (DWS) is often called in the biomedical arena, is a non-invasive method for measuring tissue blood flow based on the extensions of the dynamic light scattering (DLS) to the multiple scattering regime.

DCS measurements consist of measuring diffusely reflected light using photon counting photo detectors, and computing the temporal intensity auto-correlation curve g2(tau) for typical correlation delays from 100 ns to 1 s. These curves can be fitted using analytical expressions derived from the correlation diffusion equation to estimate scatterer motion parameters. These expression give the field auto- correlation function g1, related to the measured g2 by the Siegert relationship g2=1+beta*g1^2, where beta is a factor that depends on the detection geometry and light polarization (usually lost in tissue due to multiple scattering).

This example

Here we use an MMCM simulation of photon propagation in a thick slab (considered semi-infinite) for a symmetrical pattern of 4 2mm diameter detectors 15 mm away from a source. We turn on momentum transfer recording (the "-m" parameter in the command line), and compute the field auto-correlation curve g1 assuming Brownian diffusion like scatterer motion (shown to approximate biological tissue measurements well). We also simulate g2 by assuming a beta of 0.4 (typical for room light experimental conditions). We then fit both simulated curves using the analytical model and attempt to recover the Brownian diffusion coefficient. The 2nd example where a simulated intensity auto- correlation is fit represents the way experimental DCS data would be processed to obtain a blood flow index.

Steps

1. First, you need to create the mesh to run this example. If you have not done it already, install iso2mesh from Sourceforge:

    http://iso2mesh.sourceforge.net/cgi-bin/index.cgi?Download

2. Start Matlab, run createmesh and make a note of the value of the element ID that encloses the source (reported by the createmesh script). Edit "dcs.inp" to set line 7 to this number. If you receive errors, make sure iso2mesh is in your Matlab/Octave path

3. Run the simulation shell script "run_test.sh" from the command line. It will run 20 million photons.

4. Run "dcs_example.m" in Matlab to produce the test-figures and verify the reported fitting error is less than 5%.

Reference

Boas D.A., "Diffuse Photon Probes of Structural and Dynamical Properties of Turbid Media: Theory and Biomedical Applications", Ph.D. Thesis, Univ. of Pennsylvania, 1996

5. statnoise: Fluence variation vs photon numbers (Experimental)

Steps

1. First, you need to create the mesh files to run this example. You need to first download and install iso2mesh version 1.0 from

  http://iso2mesh.sourceforge.net/cgi-bin/index.cgi?Download

or, you can download the svn version of iso2mesh from

  svn checkout https://iso2mesh.svn.sourceforge.net/svnroot/iso2mesh/trunk/iso2mesh iso2mesh

2. Start matlab, run createmesh to create all mesh files. Matlab will print a value for variable eid. This value indicates the initial element ID in the mesh that encloses the source. You need to open vartest.json with a text editor and replace the number after "InitElem".

3. Run the simulation bash script run_test.sh, this will run the simulation for 10 repetitions and save fluence maps for 1E4, 1E5, 1E6 and 1E7 photons.

4. When all simulations complete, you start matlab again, and run plotstdhist to generate a plot between signal standard deviation and photon number.

  • This test is experimental. The interpretations to the results need
further understandings.

6. Reference:

[Fang2010] Qianqian Fang, "Mesh-based Monte Carlo method using fast ray-tracing in Plucker coordinates," Biomed. Opt. Express 1, 165-175 (2010)

Powered by Habitat