Showing revision 2.0

How to install MMC

1. Using MMC executable
2. Using MMCLAB

1. Using MMC executable

The installation of MMC is not necessary. You simply download the proper binary package that matches your operating system, extract the package, and run the software without needing to install additional libraries.

The core of the software is a self-contained single executable - mmc - in all provided binary packages. Once you extract your selected package, this executable is typically located under the mmc/src/bin directory.

To test if you have downloaded the correct MMC software, please open a terminal window (for Linux/OSX - a terminal; for Windows - command line window "cmd"), type "cd path/to/mmc/bin/src", and then run mmc without any parameter, 

 mmc

or 

 ./mmc

mmc should print out the full help information. If you don't see this information, or mmc throws an error, please verify if your downloaded package matches your operating system. If you have downloaded an SSE4 version but your CPU does not support SSE4 (made in 2008 or earlier), you will get a crash (segfault in Linux/OSX). You will have to download the multi-core version instead.

Once your have verified the correctness of your package, as the first step, you may run the built-in samples simulations in the extracted mmc package. These examples can be found under mmc/examples folder. The simplest example to run is the one under mmc/examples/onecube, because all the needed input files are provided. You just run "./run_test.sh" in a terminal. If everything goes well, you will see two output files, ad.txt and mov.txt under this folder. Once you have confidence that mmc works fine on your computer, you may move on to other more advanced examples. For most cases, you will need to generate the input mesh by executing the createmesh.m matlab script in either matlab or GNU Octave before running the simulation (typically, the execution script is named as run_test.sh).

It is important to note here, although mmc binary does not require additional libraries, the mesh generation scripts in most provided examples require you to install iso2mesh - an Open-source mesh-generation toolbox - and Matlab/GNU Octave. You can download iso2mesh from this page. The pre-processing scripts in these examples also need MATLAB/Octave to have access to the mmc/matlab folder. This can be done by typing the following two commands at the beginning of your MATLAB script, or in the MATLAB command line window: 

 addpath('/path/to/iso2mesh');
 addpath('/path/to/mmc/matlab');

After you are familiar with the provided examples, you may start creating your own simulations. Just start with one of the examples as a template, and modify the pre-processing script (createmesh.m) to insert your own geometry/object, modify the *.inp/*.json file to define your own simulation settings, and finally change the run_test.sh script to use your own simulation command line options. A typical mmc command looks like 

 /path/to/mmc -n 10000 -f inputfile.inp -D TP

Make sure you have generated all mesh files using the provided savemmcmesh() script under mmc/matlab folder. If not, you will receive an error.

For convenience, you may avoid typing the full path of the mmc executable by doing one of the following

  1. you can copy the mmc binary to one of the system directories (require administrative privilege) - for Linux: /usr/bin or /usr/local/bin directory of your system, for Windows, c:\Windows, or
  2. you can add the path containing mmc binary to your PATH environment variable. Details can be found at this page.

If your system complains about missing "libgomp.so", you are likely running a multi-threaded version of mmc but your system does not have the OpenMP libraries. This can be solved by installing the gcc package using the commands at this link, or simply download the packages with "static" in the name.

2. Using MMCLAB

If you are new to MMC and you are familiar with MATLAB, it is strongly recommended to start your MMC simulations with MMCLAB. MMCLAB is a self-contained mex file for MMC. It contains all the features in MMC but you can launch it from MATLAB or GNU Octave.

To use MMCLAB, you first download the latest MMCLAB package, extract the package, and add the path to mmclab folder in matlab by 

 addpath('/path/to/mmclab');

You should now see the [full help information when you type "help mmclab". Otherwise, check your path settings. Similarly, running MMCLAB will benefit from adding path to iso2mesh and mmc/matlab folders unless your mesh has been previously made. See above section on the addpath commands.

We provided a simple simulation example at the end of the MMCLAB help information: 

       cfg.nphoton=1e5;
       [cfg.node face cfg.elem]=meshabox([0 0 0],[60 60 30],6);
       cfg.elemprop=ones(size(cfg.elem,1),1);
       cfg.srcpos=[30 30 0];
       cfg.srcdir=[0 0 1];
       cfg.prop=[0 0 1 1;0.005 1 0 1.37];
       cfg.tstart=0;
       cfg.tend=5e-9;
       cfg.tstep=5e-10;
       cfg.debuglevel='TP';
       % populate the missing fields to save computation
       ncfg=mmclab(cfg,'prep');


       cfgs(1)=ncfg;
       cfgs(2)=ncfg;
       cfgs(1).isreflect=0;
       cfgs(2).isreflect=1;
       cfgs(2).detpos=[30 20 0 1;30 40 0 1;20 30 1 1;40 30 0 1];
       % calculate the flux and partial path lengths for the two configurations
       [fluxs,detps]=mmclab(cfgs);

This will run two simulations for a homogeneous 60x60x60 mm domain. If successful, you should see simulation outputs in the command line window. If you notice an error, check your downloaded package and make sure it matches your platform. We provided a list of demo scripts under mmclab/examples/. Please open each of the files, try to understand the overall structure and, if you like, run the simulation.

To customize the simulation, you simply replace the cfg data structure sub-fields with your own settings. Please read [[MMC/Doc/MMCLAB|MMCLAB README file] for more details.

Powered by Habitat