MCX24 Laptop Preparation instructions

1. Plan A

2. Plan B

3. Plan C

All in-person participants should have a working laptop with WIFI capability to join most of our training exercises on site. We will primarily utilize Google Colab and Jupyter Notebook running Google's cloud computing resources (GPU and CPUs) in your web browsers.

1. Plan A

To prepare for this workshop, please make sure you have a Google account. Please first download the below two files

• https://github.com/fangq/mcx/blob/master/mcxlab/tutorials/mcxlab_getting_started.ipynb
• https://github.com/fangq/mcx/blob/master/pmcx/tutorials/pmcx_getting_started.ipynb

For each of the above Jupyter Notebook file, please click on the Download icon and save a local copy to your own drive. It is strongly recommended to rename the file by attaching your full name or a date in the filename, for example renaming mcxlab_getting_started.ipynb to mcxlab_getting_started_Your_Name.ipynb or mcxlab_getting_started_20240601.ipynb

Note: the reason that we rename these Jupyter Notebook before uploading to Google Colab is because Google Colab appears to set limits not only on how many sessions one user can request (max=1 for free users), but also on how many sessions can be associated for a shared document (such as the one we provided on github). Renaming and uploading such document individually could minimize the risk of hitting such limit.

Next, please browse Google Colab at

• https://colab.research.google.com/

In the dialog "Open notebook", click on "Upload" at the bottom of the page, and select one of the .ipynb files and upload to your Google Colab environment

This will automatically open the Jupyter notebook. You should see something like below, especially a button "Connect T4" on the right-side above the document. see screenshot below

Click on "Connect T4", if you are successfully receiving a cloud GPU from Google Colab, you should see the button is shown as a green check-mark.

Alternatively, you could locate the first executable cell (shown by red circle in the below screenshot), then click on the round-arrow button to launch the virtual machine from Google Colab

You may see a warning window as below

simply click on "Run anyway". If a GPU node (called "T4 runtime") is successfully allocated, you should see a "T4/RAM/Disk" icon on the top-right corner of the page, as shown below

If you can see the above T4 runtime icon, you are in good shape. The setup script should take around 1 min to complete. Feel free to go down the document and run some of our pre-coded sample codes and see if everything runs properly (the first mcxlab/pmcx simulation will be relatively slow, but later simulations will be fast).

If you are not a paid user of Google Colab, you can only maintain maximum 1 active session. If for some reason, you have already have an opened session, when you try to run a new notebook or connect to a new runtime, you will see the below error message

you will have to click on the "Manage sessions" buttons to close a runtime that you have previously opened.

You can also list your existing sessions by selecting the drop-down button to the right of the T4/RAM/disk icon, and select menu Manage sessions.

This should give you a dialog like below

Please click on the "Trash Can" icon with a cross to the right of the session to properly close your session. Google Colab only allows 1 active session per user account. Without properly closing your opened session, you will not be able to open another new sessions (in a different, or a window, or a different computer if using the same account).

2. Plan B

If you for some reason can not allocate a T4 GPU runtime (despite you have closed all your other simultaneous sessions), you could still run most of the training materials. Our Jupyter notebook has a fall-back plan - using OpenCL based MCX-CL instead of CUDA-based MCX. MCX-CL can run on the CPU mode without needing a GPU.

To activate "Plan B" for using OpenCL mode, you should locate the 2nd executable cell on each Jupyter notebook, as shown at the bottom part of the first screenshot above ("If a GPU runtime can not be allocate ..."). Click on the execution icon should switch to the OpenCL mode.

The code in all subsequent sections should work for both MCX and MCX-CL, except that running OpenCL on the CPU is slower.

3. Plan C

Regardless whether Google Colab based Jupyter Notebook works for not, you should prepare your laptop to run MCX or MCX-CL locally. Please follow our software installation guide to install the proper packages before our workshop. In the event that both Plan A and Plan B above fails, you can at least copy/paste the related codes to your local computer and run it locally.