Monte-Carlo Simulation Software: tMCimg

Monte-Carlo Simulation

tMCimg uses a Monte-Carlo algorithm to model the transport of photons through 3D highly volumes with spatially varying optical properties and arbitrary boundary conditions. Both highly-scattering tissues (e.g. white matter) and weakly scattering tissues (e.g. cerebral spinal fluid) are supported. Using the clinical structural information provided by MRI, X-ray CT, or ultrasound, accurate solutions to the photon migration forward problem are found in times ranging from minutes to hours, depending on the optical properties and the computing resources available.

1. Introduction

: 1.1. Purpose
: 1.2. Method and References

2. Where to download and how to install

3. Detailed Usage Instructions

3.1. Directory structure

3.2. Building the tMCimg executable

3.3. Running tMCimg

3.4. Config (.inp) file format, line-by-line

: 3.4.1. Example of a .inp file with line-by-line explanatory comments.

4. Examples of using tMCimg

: 4.1. Running tMCimg on the included sample data
: 4.2. Creating all input data from scratch, then running tMCimg

5. Bug Report and Discussion Forum

6. Collaboration and Development

7. References

1. Introduction

This section describes the purpose of the tMCimg application, and the basic algorithm/method implemented in the software.

1.1. Purpose

Light transport in highly-scattering medium, such as human tissue, is a complex process. The photons go through a large number of scattering and absorption events when traveling through the volume. Monte-Carlo is a statistical approach which models the light transport process in such scenario.

With this software package, we provide an efficient implementation of the Monte-Carlo method for modeling the light transport process in arbitrarily-shaped 3D target (represented by voxelized space), for both high or low-scattering medium. This program is not only able ot compute the static distributions of photons in complex media, but also capable of modeling the temporal propagation of light in such media, which is critically important for data analysis in time-domain optical imaging systems.

1.2. Method and References

The details of our implementation and validation of this code can be found in the following paper [Boas2002, see Reference Section]. If you use this code in your research, the authors of the paper are appreciated if you can add the citation in your related publications.

2. Where to download and how to install

Download tMCimg

The source code of tMCimg is currently maintained at our ORBIT gforge website under the project name "Brain Dynamo". The URL of the project

https://orbit.nmr.mgh.harvard.edu/projects/braindynamo/

You can download the released versions of this software can be found at

https://orbit.nmr.mgh.harvard.edu/frs/?group_id=29

The latest development version are accessible via CVS (concurrent version control) system at

https://orbit.nmr.mgh.harvard.edu/scm/?group_id=29

Prepare for CVS download

If you want to get the latest development branch of tMCimg, you can download it from our cvs. First, make sure you have installed cvs client on your system. If you are using Debian-based GNU/Linux systems (such as Ubuntu, Knoppix etc), you can install cvs by

 sudo apt-get install cvs

if you are using Redhat-based GNU/Linux systems (such as Fedora, CentOS etc), you can do this by

 sudo yum install cvs

If your operation system is Windows, we recommend you to install TortoiseCVS.

Anonymous CVS Download

This project's CVS repository can be checked out through anonymous (pserver) CVS with the following instruction set. The module you wish to check out must be specified as the modulename. When prompted for a password for anonymous, simply press the Enter key.

 cvs -d :pserver:anonymous@orbit.nmr.mgh.harvard.edu:/cvsroot/braindynamo login
 cvs -d :pserver:anonymous@orbit.nmr.mgh.harvard.edu:/cvsroot/braindynamo checkout montecarlo

If you are using Windows, please check out TortoiseCVS website for the tutorial how to download code using the GUI (basically, right click on the file explorer, and select menu CVS\CVS checkout...).

Developer CVS Access via SSH

Only project developers can access the CVS tree via this method. SSH must be installed on your client machine. Substitute modulename and developername with the proper values. Enter your site password when prompted.

 export CVS_RSH=ssh
 cvs -d :ext:developername@orbit.nmr.mgh.harvard.edu:/cvsroot/braindynamo checkout montecarlo

Installing tMCimg

This section details the instructions to install the software on various commonly used operating systems. Because this program only uses the standard ANSI C implementations, the compilation of the code is relatively straightforward on various operating systems. It normally requires a minimum installation of a standard C/C++ compiler and the related libraries.

Windows

In order to compile tMCimg on windows you need to have a C compiler installed; two of the commonly uesd ones:

Borland C++ Compiler (or C++ Builder) (any version)
Microsoft Visual C++ Compiler (any version)

The following instructions have been tested for Borland C++ Compiler v.5.5.1 on Windows XP:

1. In a DOS shell, check the values of the environment variables CC_ROOT_PATH, CC_INCLUDE_PATH, and CC_LIB_PATH by typing

   echo %CC_ROOT_PATH%
   echo %CC_INCLUDE_PATH%
   echo %CC_LIB_PATH%

If the paths in these variable do not match the paths of your compiler then open the install_win.bat file in a text editor and set them to reflect the installation paths of your Borland C++ compiler.

2. Then run install_win.bat by typing

   call install_win.bat in

at the DOS prompt. This should create the makefiles specific to the Windows and Borland C++ Compiler environment.

3. Now you're ready to compile: from the root montecarlo directory type make, make opt (for best performance) or make debug (to be able to the load and run in a debugger)

Linux

To compile the code from source, you need to have gcc installed in your system. This can be done by sudo apt-get install build-essential in Debian based systems (such as Ubuntu), or sudo yum install gcc in Fedora/Redhat based distributions.

To compile tMCimg first create the makefiles for the linux environment by running the install_linux.sh shell script from the root montecarlo directory. Then type make, make opt (for best performance) or make debug (to be able to the load and run in a debugger)

Mac OS

This will be added later

3. Detailed Usage Instructions

3.1. Directory structure

After downloading the montecarlo module you should have a directory structure like this:

        	 montecarlo
        	     |
        	     |
  bin/  CVS/  example/  makefile  obj/  src/

3.2. Building the tMCimg executable

Go to the root directory under ./montecarlo and type make on the command line. This should create the tMCimg executable under ./bin.

  cd <path name to root>/montecarlo
  make

3.3. Running tMCimg

To run tMCimg you have to have two files: a config file with a .inp extension and a segmentation file. tMCimg takes one argument, the .inp file which has a reference to the segmentation file. See 4 for explanation of how to create a config file

Example:

We have the config file babyXX2.inp and a segmentation file baby_XXwks.bin. The reference to baby_XXwks.bin is in babyXX2.inp. To run you can do the following

  cd ./montecarlo
  ./bin/tMCimg babyXX2

3.4. Config (.inp) file format, line-by-line

 line 1:	number of photons							 
 line 2:	seed for generating random path for each photon
 line 3:	3D coordinates of the source in mm
 line 4:	vector showing initial direction of photons as they   
		enter the medium from the source. 
 line 5:	temporal gates: start, stop and step size (in s). If the 
		step size is bigger than start minus stop time, then  
		tMCimg will record only one time period
 line 6:	pathname of tissue segmentation file  
 line 7:	the first two numbers specify the voxel size (in mm) 
                and volume dimension along x axis, respectively; 
		the last 2 numbers: start/end indices along the x axis, 
		the photon propagation and fluence recording will be 
		limited to that region
 line 8:	same for y axis
 line 9:	same for z axis
 line 10:	number of tissue types
 line 11:	properties of tissue 1: scattering (mus); anisotropy (g); 
		absorption (mua); refraction (n)
		       . . . . . . . 
 line 11+m:	same for tissue m
 line 11+m+1:	number of detectors and radius of detector (in mm)
 line 11+m+2:	3D coordinates of detector 1 (in mm)
		       . . . . . . . 
 line 11+m+2+n: 3D coordinates of detector n (in mm						   )

3.4.1. Example of a .inp file with line-by-line explanatory comments.

 10000000	   -- number of photons
 -4896744	   -- seed for generating random path for each photon
 242   110   107   -- source 3D coordinates in mm
 -1 0 0 	   -- vector showing initial direction of photons as  
		      they enter the medium from the source.
 0 5e-9 6e-9	   -- temporal gates: start, stop and step size (in s)
 baby_XXwks.bin    -- tissue segmentation file 
 1 308   1 308     -- along x axis: voxel size in mm, x dimension 
		      last 2 numbers: start/end indices of the 
		      region-of-interest in x dimension
 1 308   1 308     -- same for y axis
 1 308   1 308     -- same for z axis
 4		   -- number of tissue types
 0.75 0.01 0.009 1 -- properties of tissue 1: scattering (mus), 
        	      anisotropy (g), absorption (mua), refraction (n)
 0.5  0.01 0.002 1 -- same for tissue 2 
 0.5  0.01 0.005 1 -- same for tissue 3
 0.5  0.01 0.005 1 -- same for tissue 4
 11 2		   -- number of detectors, radius of detector
 245   110   116   -- detector  1 3D coordinates in mm
 247   110   126   -- detector  2 3D coordinates in mm
 247   110   136   -- detector  3 3D coordinates in mm
 247   110   146   -- detector  4 3D coordinates in mm
 246   110   156   -- detector  5 3D coordinates in mm
 243   110   166   -- detector  6 3D coordinates in mm
 241   110   176   -- detector  7 3D coordinates in mm
 238   110   186   -- detector  8 3D coordinates in mm
 235   110   195   -- detector  9 3D coordinates in mm
 230   110   203   -- detector 10 3D coordinates in mm
 225   110   212   -- detector 11 3D coordinates in mm

4. Examples of using tMCimg

4.1. Running tMCimg on the included sample data

The montecarlo module available on orbit includes sample data for running tMCimg; that is segmentation and config files. They are included with the under ./example/sphere.

To run tMCimg on the example data, simply do the following from the root montecarlo directory (on Linux):

 cd ./example/sphere
 ./runmc40.sh
 ./runmc80.sh

This will create data for the 2 separate examples; one for the 40x40x40 segmented sphere with 2 tissue types, 1 source and 1 detector and one for the 80x80x80 segmented sphere with 2 tissue types, 1 source and 1 detector. After running the scripts (which run tMCimg) you can examine the outputs (the .2pt and .his files) in Matlab.

4.2. Creating all input data from scratch, then running tMCimg

In this section, we demonstrate how to prepare and run a simulation session using Matlab and tMCimg. We will generate a 100x100x100 volume with 4 tissue types, and place 5 optodes on the surface and run tMCimg with 5 million photons on each optode.

a) Generate a 100x100x100 segmentation volume with 4 tissue types. Name it seg.bin

  seg = zeros(100,100,100);
  seg(:,:,10:25) = 1;
  seg(:,:,26:50) = 2;
  seg(:,:,51:75) = 3;
  seg(:,:,76:end) = 4;
  fid = fopen('seg.bin', 'wb');
  fwrite(fid, seg, 'uint8');
  fclose(fid);

b) Position the source and 4 detectors at the following locations

  s1: (50, 30, 10)
  d1: (50, 35, 10)
  d2: (50, 25, 10)
  d3: (55, 30, 10)
  d4: (45, 30, 10)

generating 5 million photons and one time gate.

Create the .inp config files for all optodes for which you want to create a 2pt fluence file. For instance, for source 1, you can create a file named sample.s1.inp. (The file name is arbitrary for tMCimg as long as it has a .inp extension. But it's a good idea to include the optode type and number to know which optode the config file uses as the source.)

Here's what the contents of two of the 5 input files - sample.s1.inp and sample.d1.inp - might look like:

sample.s1.inp:

  5000000
  -75126705
  50.0 30.0 10.0
  0.0 0.0 1.0
  0 5.000000e-09 5.000000e-09
  ./seg.bin
  1 100 1 100
  1 100 1 100
  1 100 1 100
  4
  0.660000 0.001000 0.019100 1.000000
  0.860000 0.001000 0.013600 1.000000
  0.010000 0.001000 0.002600 1.000000
  1.100000 0.001000 0.018600 1.000000
  4 1
  50.0        35.0    10.0
  50.0        25.0    10.0
  55.0        30.0    10.0
  45.0        30.0    10.0

sample.d1.inp:

  5000000
  -25509511
  50.0 35.0 10.0
  0.0 0.0 1.0
  0 5.000000e-09 5.000000e-09
  ./seg.bin
  1 100 1 100
  1 100 1 100
  1 100 1 100
  4
  0.660000 0.001000 0.019100 1.000000
  0.860000 0.001000 0.013600 1.000000
  0.010000 0.001000 0.002600 1.000000
  1.100000 0.001000 0.018600 1.000000
  4 1
  50.0        30.0    10.0
  50.0        25.0    10.0
  55.0        30.0    10.0
  45.0        30.0    10.0

Then on the command line in whichever shell you're running, run tMCimg for each optode you need. In this example there are 5 optodes, so to get fluence data for all the optodes run tMCimg 5 times, without including the .inp extension, like this:

 tMCimg sample.s1
 tMCimg sample.d1
 tMCimg sample.d2
 tMCimg sample.d3
 tMCimg sample.d4

This will generate the .2pt and .his files for all 5 optodes.

5. Bug Report and Discussion Forum

The bug reporting and discussion forum are still works in progress, soon to be revisited.

6. Collaboration and Development

The project is licensed under a BSD license (please read the details in the LICENSE). This means that users can not only use the program, but also can be involved in the collaborative development of the program. The maintainer of this software are very excited to see more developers contribute to this software.

The latest code can be accessed from our CVS repository at https://orbit.nmr.mgh.harvard.edu/scm/?group_id=29 where the module name is "montecarlo". One can also browse the latest source code from https://orbit.nmr.mgh.harvard.edu/plugins/scmcvs/cvsweb.php/montecarlo/?cvsroot=braindynamo

Users can download the program without creating a gforge account. However, if one wants to be involved in the development, one can consider the following:

if your change is relatively small, submit your changes as a patch file, send it to our current maintainer and they will review the patch and add it to the main source code tree
or if you want to be involved in the maintaining, forking, adding new modules or significantly rewrite the code, please discuss it with our maintainer and we will consider to add you to the developer list so that you can commit changes to the cvs repository.

7. References

Boas DA, Culver JP, Stott JJ, and Dunn AK. "Three dimensional Monte Carlo code for photon migration through complex heterogeneous media including the adult human head" Opt. Express 10: 159-170 (2002).