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. 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
  |-misctest   - other misc. tests
  |-mouse      - legacy example
  |-sphbox     - legacy example

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. 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