MCX'18 Workshop Preparation Instructions

To participate this workshop, you need to bring your own laptop. You can run the training sessions directly using your laptop or using a sever that can be remotely accessed (via Remote Desktop for a Windows server, vnc for Mac, and x2go for Linux). A more powerful discrete graphics card is recommended, but you can still use the CPU or the integrated GPU to run the training materials.

The computer that runs the training sessions (either your laptop or the remote server) must be prepared before the workshop. Please find the instructions below on how to prepare your computer for this workshop.

1. Preparation of your Laptop

We assume you use one of the 3 supported configurations:

a 64bit Windows
a 64bit Linux computer, or
a 64bit Mac with Intel CPU

if you use a 32bit operating system (such as 32bit Windows XP), you must let us know in advance.

In most cases, you don't need to do anything for Steps 1-2 below if you have installed your graphics card driver properly.

1.1. Step 1. Verify your CPU/GPU support

We will use MCX-CL as our primary tool for demo and training, although the operations using MCX/MMC are very similar.

MCX-CL supports a wide-range of processors, including Intel/AMD CPUs and GPUs from NVIDIA/AMD/Intel.

1.1.1. Verify GPU/CPU support

To verify if you have installed the OpenCL or CUDA support, you may

if you have a windows machine, download and install the Everything Search tool (a small and fast file name search utility), and type "opencl.dll" in the search bar
- Expected result: you must see OpenCL.dll (or nvopencl.dll if you have an NVIDIA GPU) installed in the Windows\System32 directory.
if you have an Mac, open a terminal, and type ls /System/Library/Frameworks/OpenCL.framework/Versions/A/OpenCL
- Expected result: you should not see an error.
if you have a Linux laptop, open a terminal, and type locate libOpenCL.so,
- Expected result: you should see one or multiple libOpenCL files

Example screenshot from a laptop with integrated GPU

Example screenshot from a computer with dedicated NVIDIA GPU

If the OpenCL.dll file is not found on your system, please read the below sections. Otherwise, please go to Step 2.

1.1.2. Laptops without discrete GPUs

In most cases, your laptop runs on an Intel CPU with integrated graphics. In this case, please make sure you have installed the latest Intel graphics drivers. If you are certain that you have installed the graphics drivers, or your graphics works smoothly, please skip this step.

If you want to double check, for Windows machine, you can download the "Intel Driver&Support Assistant" to check if you have installed the graphics drivers

https://downloadcenter.intel.com/download/24345/Intel-Driver-Support-Assistant

for a Mac, you need to use your App store to update the driver, see the below link for details

https://www.intel.com/content/www/us/en/support/articles/000022440/graphics-drivers.html

1.1.3. Laptops with discrete GPUs

if you want to bring a beefy laptop with discrete GPU to the workshop, you need to make sure your discrete GPU is configured with the appropriate GPU driver installed. Again, if you have been using your laptop regularly and the graphics has been smooth, likely your graphics driver has already been installed.

If your GPU driver was not installed, and would like to install, or upgrade from an older version, for an NVIDIA GPU, you may browse this link to install the matching driver

http://www.nvidia.com/Download/index.aspx

if your GPU is an AMD GPU, please use the below link

https://support.amd.com/en-us/download

It is also possible to simultaneously access Intel CPU along with your discrete GPU. In this case, you need to download the latest Intel OpenCL Runtime for CPU only.

https://software.intel.com/en-us/articles/opencl-drivers#latest_CPU_runtime

Note: if you have an NVIDIA GPU, there is no need to install CUDA in order for you to run MCX/MCXLAB.

1.2. Step 2. Install MATLAB

MATLAB is needed for the majority of the training. You must install a working copy of MATLAB before the event. If you do not have a license, you may download a trial version of MATLAB. The trial version has a 30-day limit.

If you run a Linux laptop, you can, but not recommended, to install the latest version of GNU Octave. It supports Linux/Windows/Mac.

To verify your computer has MATLAB installed, you must be able to see the MATLAB icon and start it without any problem.

1.3. Step 3. Download the MCXStudio software package

Our developed MCX/MMC/MCXCL tools are packaged in a single zip file, available for you to download at

http://mcx.space/nightly/

Please click on the folder matching your operating system (for example, if you run a 64bit Windows, you need to navigate into win64 folder), and download the file named "MCXStudio-nightlybuild.zip".

Open this file, and unzip it to one of your working folder. The package needs about 50MB disk space.

Once unzipped, you should be able to see a folder named "MCXStudio", with a few executable and 3 subfolders underneath. See the folder structure below:

MCXStudio
├── MATLAB
│   ├── mcxlab
│   │   ├── examples
│   │   ├── mcxlab.m
│   │   ├── ...
│   │   ├── mcx.mex
│   │   ├── mcx.mexa64
│   │   ├── mcxpreview.m
│   │   └── README.txt
│   ├── mcxlabcl
│   │   ├── examples
│   │   ├── ...
│   │   ├── mcxcl.mexa64
│   │   ├── mcxlabcl.m
│   │   └── README.txt
│   └── mmclab
│       ├── example
│       ├── ...
│       ├── mmc.mex
│       ├── mmc.mexa64
│       └── README.txt
├── mcxstudio
├── mcx
├── mmc
├── mcxcl
├── MCXSuite
│   ├── mcx
│   │   ├── bin
│   │   ├── doc
│   │   ├── example
│   │   ├── ...
│   │   └── utils
│   ├── mcxcl
│   │   ├── bin
│   │   ├── ChangeLog.txt
│   │   ├── doc
│   │   ├── example
│   │   ├── ...
│   │   └── utils
│   └── mmc
│       ├── bin
│       ├── examples
│       ├── matlab
│       ├── ...
│       └── src
└── Output

Please make sure your downloaded MCXStudio must match your operating system.

1.4. Step 4. Start MCXStudio and query GPU information

Now, navigate to the MCXStudio folder (i.e. the top folder of the extracted software structure). On Windows, double click on the executable named "mcxstudio.exe"; on the Mac, double click on an app named "mcxstudio" with a red MCX logo; on the Linux, double click on the mcxstudio executable.

You should see the below interface.

Click on the "New" button to the top-left (green plus icon), select the 3rd option "NVIDIA/AMD/Intel/ CPUs/GPUs (MCXCL)", and type a session name "preptest" in the field below. Then click OK. You should see a blue/yellow preptest icon added to the left panel.

Now, click on the "GPU" button on the toolbar (6th button from the left side), an Output window will popup, and wait for a few seconds, you should see an output like

"-- Run Command --"
"/drives/taote1/users/fangq/Download/MCXStudio/MCXSuite/mcxcl/bin/mcxcl" -L
"-- Printing GPU Information --"
Platform [0] Name NVIDIA CUDA
============ GPU device ID 0 [1 of 2]: Graphics Device  ============
 Device 1 of 2:		Graphics Device
 Compute units   :	80 core(s)
 Global memory   :	12644188160 B
 Local memory    :	49152 B
 Constant memory :	65536 B
 Clock speed     :	1455 MHz
 Compute Capacity:	7.0
 Stream Processor:	10240
 Vendor name    :	NVIDIA
 Auto-thread    :	655360       
...
Platform [1] Name Intel(R) OpenCL
============ CPU device ID 2 [1 of 1]: Intel(R) Core(TM) i7-7700K CPU @ 4.20GHz  ============
 Device 3 of 1:		Intel(R) Core(TM) i7-7700K CPU @ 4.20GHz
 Compute units   :	8 core(s)
 Global memory   :	33404575744 B
 Local memory    :	32768 B
 Constant memory :	131072 B
 Clock speed     :	4200 MHz
 Vendor name    :	Intel
 Auto-thread    :	512
 Auto-block     :	64

"-- Task completed --"

If you do not see any output, or it returns no GPU found, that means your OpenCL support was not installed properly. Please go back to Step 1-3 and reinstall the drivers.

If you have Intel CPU with Integrated GPU, you should be able to see a section with "Platform [?] Name Intel(R) OpenCL" in the above output. You may see only the CPU is listed, or both the CPU and the integrated GPU.

1.5. Step 5. Run a trial simulation

If your above GPU query was successful, you should now see in the middle panel of the MCXStudio window, in the Section titled "GPU Settings", under "Run MCX on", a check-box list, you should now see the available devices on your laptop.

To avoid running lengthy simulations, please change the "Total photon number (-n)" field under the "Basic Settings" from 1e7 to 1e5.

Now, you can then run a trial simulation, by first clicking on the "Validate" button (blue checkmark icon), and then click on "Run" (the button to the right of validate). This will launch an MCXCL simulation. The output window will show again, and you can see the messages printed from the simulation, similar to the output below

"-- Command: --"
mcxcl --session "preptest"  --input "/drives/taote1/users/fangq/Download/MCXStudio/Output/mcxclsessions/preptest/preptest.json" --root "/drives/taote1/users/fangq/Download/MCXStudio/Output/mcxclsessions/preptest" --outputformat mc2 --gpu 10 --autopilot 1 --photon 10000000 --normalize 1 --save2pt 1 --reflect 1 --savedet 1 --unitinmm 1.00 --saveseed 0 --seed "1648335518" --compileropt "-D USE_ATOMIC" --array 0 --dumpmask 0 --repeat 1  --maxdetphoton 10000000
"-- Executing Simulation --"
unknown verbose option --saveseed
==============================================================================
=                       Monte Carlo eXtreme (MCX) -- OpenCL                  =
=          Copyright (c) 2010-2018 Qianqian Fang <q.fang at neu.edu>         =
=                             http://mcx.space/                              =
=                                                                            =
= Computational Optics&Translational Imaging (COTI) Lab - http://fanglab.org =
=            Department of Bioengineering, Northeastern University           =
==============================================================================
=    The MCX Project is funded by the NIH/NIGMS under grant R01-GM114365     =
==============================================================================
$Rev::6e839e $ Last $Date::2017-07-20 12:46:23 -04$ by $Author::Qianqian Fang$
==============================================================================
- variant name: [Detective MCXCL] compiled with OpenCL version [1]
- compiled with: [RNG] Logistic-Lattice [Seed Length] 5
initializing streams ...	init complete : 0 ms

Building kernel with option: -cl-mad-enable -DMCX_USE_NATIVE -DMCX_SIMPLIFY_BRANCH -DMCX_VECTOR_INDEX -DMCX_SRC_PENCIL  -D USE_ATOMIC -DUSE_ATOMIC -D MCX_SAVE_DETECTORS -D MCX_DO_REFLECTION
build program complete : 23 ms
- [device 0(1): Graphics Device] threadph=15 oddphotons=169600 np=10000000.0 nthread=655360 nblock=64 repetition=1
set kernel arguments complete : 23 ms
lauching mcx_main_loop for time window [0.0ns 5.0ns] ...
simulation run# 1 ... 

kernel complete:  	796 ms
retrieving flux ... 	
detected 0 photons, total: 0	transfer complete:        818 ms
normalizing raw data ...	normalization factor alpha=20.000000
saving data to file ... 216000 1	saving data complete : 821 ms

simulated 10000000 photons (10000000) with 1 devices (repeat x1)
MCX simulation speed: 12953.37 photon/ms
total simulated energy: 10000000.00	absorbed: 27.22654%
(loss due to initial specular reflection is excluded in the total)

If this simulation is completed successfully, you should be able to see the "Simulation speed" and total simulated energy reported at the end.

1.6. Step 6. Test MATLAB for visualization

Once this above simulation is completed, you can click on the "Plot" button on the toolbar, and from the drop-down menu, select "Plot fluence (mc2)". This will open an MATLAB window, and show you an iterative figure so you can visualize the image slices.

If MATLAB can not be started, you may not install MATLAB properly, or haven't added MATLAB executable to your PATH environment variable.

1.7. Step 7. Setting up MATLAB search path for MCXLAB/MMCLAB training

The next step is to set up the search paths for MCXLAB/MMCLAB. You need to start MATLAB, and in the Command window, please type

 pathtool

this will popup a window. Click on the "Add with Subfolders ..." button (the 2nd from the top), then browse the MCXStudio folder, then select OK. Now you should see all needed MCX/MMC paths are added to MATLAB. Before you quick this window, click on the "Save" button.

To verify if your MCXLAB/MMCLAB/MCXLABCL has been installed properly, please type

 which mcxlab
 which mmclab
 which mcxlabcl

you should see their full paths printed.

To see if you can run MCXLAB-CL in your environment, please type

 info=mcxlabcl('gpuinfo')

this should print a list of CPU/GPU devices using which you can run the MC simulations.

If you do not see any output, that means your CPU/GPU OpenCL driver was not installed properly, you need to go back to Steps 1-2.

If you have an NVIDIA GPU, and have installed the proper GPU driver, you may run

 info=mcxlab('gpuinfo')  % notice the command is mcxlab instead of mcxlabcl

this should print a list of NVIDIA GPU from the MATLAB window.