MCX19 Laptop Preparation instructions

1.1. Laptop requirements
1.2. MCX software download and preparation
1.3. Test MCXCL in MCXStudio
1.4. Run a trial MCXCL simulation in MCXStudio
1.5. Configure MATLAB
1.6. Additional Information

In this workshop, we will use MCXCL (MCX-OpenCL) as the primary tool to teach our participants how to use our software. MCXCL can be executed on a wide range of CPUs and GPUs), therefore, we expect that every participant should be able to complete the training using only his/her own laptop.

1.1. Laptop requirements

Before coming to the workshop, we strongly encourage all participants preparing your laptop and make sure they can run our software. The requirements to the laptop is quite minimal - as long as you have an Intel CPU (preferably, newer than 4-th generation) or an AMD CPU made over the past 4 years, you will be able to run our software. Although, if you have access to a laptop with a discrete NVIDIA or AMD GPU, that will make the simulation much faster, but it is not required.

On the software side, your laptop must have

  1. a pre-installed MATLAB (if you do not have a license, you can get a trial version)
  2. the latest graphics (or GPU) driver. we assume you have a working graphics system (that can display 3D graphics), if your graphics is not working, please install the latest driver from the vendor's website

You DO NOT need to install CUDA run-time or other special libraries. Our software will contain all needed libraries.

1.2. MCX software download and preparation

We provided precompiled, ready-to-use packages for 64bit Linux, Windows and Mac OSX. You must download the latest all-in-one package - MCXStudio-* from our website

and unzip the all-in-one package to a directory - for example, you can unzip the package to Documents/MCXStudio/. We refer to this unzipped package top folder as the <Root> folder in the remaining of this document.

Special instructions for Windows

For Windows users, you need to navigate to the <Root>/MCXSuite/mcx/setup/win64/ folder in the File Browser, and right-click on the apply_timeout_registry_fix.bat file, and select "Run as administrator". This will apply a patch to let your computer run MCX for more than 2 seconds. Once the patch is applied, you MUST REBOOT your laptop to activate the setting.

If you see the below error

  error: OpenCL extension 'cl_khr_fp64' is unsupported
Please browse this link to install the latest Intel OpenCL CPU run-time.

Special instructions for Mac

For Mac users, you need to open a terminal, cd the <Root> folder, and run

 xattr -dr .

in the terminal. Otherwise, when you double click on the mcxstudio application, you will get an error.

1.3. Test MCXCL in MCXStudio

The next step of the preparation is to test a couple of MCXCL simulations in MCXStudio - a graphical user interface for MCX.

To start MCXStudio, go to the <Root> folder and double click on mcxstudio.exe (for Windows), mcxstudio (for Linux) or mcxstudio with a red-icon (not the one with a black icon) on the Mac.

You should see the MCXStudio main window displayed. At the bottom of the window, you should see a printed line such as


where <Root> is the actual local folder name. If you see an empty path after EXEPATH=, that means your MCXStudio folder structure is incorrect. Please download again and repeat the above steps.

To do a test, you need to

  1. click on the "New" button on the toolbar,
  2. select the 3rd option - "NVIDIA/AMD/Intel CPUs/GPUs (MCX-CL)",
  3. then type "test" in the session name,
  4. click OK,
  5. then click the "GPU" icon on the toolbar

Now, in the output area located at the bottom of the window, you should see at least 1 CPU or GPU information is printed. If you see any missing files or errors, you may have a partially installed driver or MCXStudio package. Please contact Dr. Fang for further help.

1.4. Run a trial MCXCL simulation in MCXStudio

If you can see a CPU or GPU is listed, you can simply select one of the listed CPU/GPU from the GPU settings\Run MCX on section, by checking the desired device. Then, you should click the "Validate" button on the toolbar. Then click "OK". This will start a default simulation with 10^6 photons. If everything goes well, you should see outputs in the Output area below. This simulation should typically be done within 5-20 seconds (depends on your device). If anything prevents the simulation to be completed, you should see an error message.

If the trial simulation completes without an error, you should now be able to plot the results. You should click on the "Plot" icon on the toolbar, and select "Plot fluence (mc2)". A volumetric rendering of the generated fluence map should be displayed.

Special instructions for Mac

If you have a Mac laptop, there are several known issues running simulations using MCXStudio

  1. First, if you select the Intel CPU to run mcxcl simulation, it will give you an "invalid workgroup" error. This is a known issue, bcause Apple's CPU OpenCL driver does not support a workgroup size larger than 1. To avoid this problem, you must
    1. uncheck "Let MCX decide thread/block size" in the GPU Settings section
    2. set Thread number to 256, and Thread Block size to 1.
Then, rerunning the simulation will complete successfully. You CAN check "Show progress bar" when using the CPU.
  1. If you have an AMD GPU, while it can complete the simulation without changing the block size, please DO NOT check "Show Progress Bar", otherwise, it will hang
  2. If you have an AMD R9 GPU, selecting "Preview" or plotting submenus in the "Plot" drop-down menu will generate a crash and log out your current session. This is also a known problem and is related to OpenGL support in the library we used. If you have an Intel GPU, this is not a problem.
  3. Running simulations using either the command line tools in the terminal, or in MATLAB is fine. The above issues only affect MCXStudio. If your laptop contains an AMD R9 GPU, we strongly suggest you to install Bootcamp and a Windows partition, and use the Windows MCXStudio to go through the training.

1.5. Configure MATLAB

The last step of the preparation is to setup MATLAB to run mcxlab/mmclab. To do that, you need to open MATLAB, and cd the <Root> folder, and run a script named mcxsuite_addpath.m. Once you execute this command, all necessary toolbox paths are added to MATLAB.

To test, you should first run

 which mcxcl

this should print the full path point to the mex file located at <Root>/MATLAB/mcxlabcl/mcxcl.mex*. Then you may run


this should print out the supported OpenCL CPUs/GPUs on your system.

If you are able to see the printed information, the setup is complete.

1.6. Additional Information

If the above instructions generated errors or issues that can not be fixed, please post your question to the mcx-users mailing list, or email Dr. Fang directly.

Alternatively, you may also consult the more detailed preparation instructions we used for previous workshops. These instructions may contain extra steps that are no longer needed, however, it covers more options.

You should try the below 3 approaches in order until you find one that works for you.

  • Method A (recommended) - Running everything from your laptop (or remote server in your own lab)

This way, you will have a working system after getting back from the workshop and ready to run new simulations.

In the event that your laptop is too old, or have driver issues and unable to use the CPU/GPU for our simulations, we will ask you to try the alternative approach:

  • Method B - Use remote GPU via MCXStudio from your laptop

If the above approach (Method B) still unable to allow you to connect and run simulations, we will have to use our preconfigured Linux-based environment, this is our fall-back plan:

  • Method C - Run simulations over the remote desktop of our Linux GPU server

Because of limited network bandwidth, we do not recommend Method C to everyone, but only use it when the previous two approaches fail.

If you have difficult configuring your laptop, please consider borrowing another laptop or run a remote server in your home institution. Please test connections if you decide to run the simulations on your server.

Powered by Habitat