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.
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
You DO NOT need to install CUDA run-time or other special libraries. Our software will contain all needed libraries.
We provided precompiled, ready-to-use packages for 64bit Linux, Windows and Mac OSX. You must download the latest all-in-one package - MCXStudio-*-nightlybuild.zip 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.
If you see the below error
error: OpenCL extension 'cl_khr_fp64' is unsupportedPlease browse this link to install the latest Intel OpenCL CPU run-time.
xattr -dr com.apple.quarantine .
in the terminal. Otherwise, when you double click on the mcxstudio application, you will get an error.
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
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.
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.
If you have a Mac laptop, there are several known issues running simulations using MCXStudio
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
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.
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.
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:
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:
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.