NBCR Summer Training 2018

This tutorial will start with an introduction of the mesoscale and the different tools we developed in the MGL lab, as well as an overview of the tutorial. The tutorial will be conducted by: Brett Barbaro, Ludovic Autin, Adam Gardner, and Andrew Jewett.

Initial Preparation

- you need a recent browser like Firefox or Chrome

- you need Blender plus the plugins

Download the bundle for your OS :

Bundle for Windows 64bits

Note for Windows User:

if the plugin doesnt start, try to install the visual C++ redistributable for vs2015 https://www.microsoft.com/en-us/download/details.aspx?id=48145

Bundle for MAC OS 64bits

Note for Mac user:

Unzip the package in your user>Downloads folder.

We provide an alias to run Blender in the terminal, so do not double-click blender.app - double-click "run_blender.command" instead.

If it doesn't work, open the "run_blender.command" file in a text editor and replace the path to Blender by the one you have download Blender into.

Bundle for Linux 64bits

Note for Linux user:

install/unzip in your user folder

before running ./blender you need to update the LD_LIBRARY_PATH to point to the MGLToolsPckgs. e.g export LD_LIBRARY_PATH=/pathtoblender/MGLToolspckgs:$LD_LIBRARY_PATH;./blender

Start Blender, ePMV and autoPACK should appear on the top right of the window.
If they dont, you need to activate them in blender user preferences"
1. In the top left menu Click File > User Preferences (Follow image below)
2. Click on the Add-Ons Tab
3. Click the System Category to simplify the list
4. Check [√] autoPACK
5. Check [√] ePMV
6. Check [√] ePMV synchro
7. Click [Save As Default]
8. Click File > Save User Setting

We recommend user to check the blender reference manual and the getting started section: https://docs.blender.org/manual/en/dev/.

Recipe Preparation - Mesoscope

Overview

Go to : https://mesoscope.scripps.edu/beta/

If you have problem with webGL try to enable it (e.g. see here )

Preparing the recipe hierarchy

click on Layout Options->Show Object Properties
click on Load->New recipe->Empty recipe
in recipe option tab, under recipe options check "Edit mode"
click on "Add Compartment"
right-click on the compartment, and select rename.
rename "newCompartment1" to "comp1" ( no space or special character )
click on the created compartment, and in the widget right to it (NGL View), in the compartment properties, select MetaBalls as the source of the compartment, and specify a radius of 250A. ( we will use only one metaball, which is a sphere )
click on "Add Ingredient" (You might need to zoom out or recenter to see it - scroll to zoom, middle-click and drag to move.)
right-click on the ingredient, and select rename. (note: you can also specify a custom color for it)
rename to "ElongationFactor" ( no space or special character )
select and drag the created node inside the compartment
click on "Add Ingredient"
right-click on the ingredient, and select rename.(note: you can also specify a custom color for it)
rename to "ABCtransporter" ( no space or special character )
select and drag the created node to the surface of the compartment (on the circumference of the circle)
click on "Add Ingredient"
right-click on the ingredient, and select rename.(note: you can also specify a custom color for it)
rename to "IgG"
switch off Edit Mode (in the Recipe View window) by clicking on the toggle button - the "Add ingredient" and "Add compartment" buttons should disappear

Note: If you changed the nodes color, you can view it in the canvas by changing the pull-down color to "color"

At this point you should have the following visual (the locations of your ingredients may differ depending on where you dropped them, but that doesn't matter):

Gathering the structural and geometrical data for each ingredient

Elongation Factor

In the "Recipe table" widget (the spreadsheet on the bottom), double click in the cell corresponding to the "ElongationFactor" row, "pdb" column. Enter the PDB id 1efg.The "NGL View" window should update and load the structure in NGL, as well as updating the "NGL options" and "ingredient properties" panels
Click on "NGL options" to display the options panel if not already visible (you may need to resize the window to see it clearly).
Click on the "Rebuild Geometry" button - this will generate a coarse molecular surface that can be toggled on/off with the "Show Geometry used" checkbox
Next to "Show Beads", in the pull down menu, select the entry "0" if it's not already done
Dial the slider number of cluster to 10 (if it's already at 10, you can just click it) - this will apply the K-means algorithm on the atom positions to generate a 10-bead representative cluster. (Note - your bead representation may not look exactly like the one pictured here. This is normal. There is an element of randomness in the algorithm, so it will look different every time.)

ABCtransporter

In the "Recipe table" widget double click in the cell corresponding to the "ABCtransporter" row, "pdb" column. Enter the PDB id 1l7v (that's the number one followed by a lower-case "L" - case matters!).The NGL View should update and load the structure in NGL, as well as updating the "NGL options" and "Ingredient properties" panels
This a membrane protein - mesoscope will first check if the given structure exists in the OPM database. If found, the weblink at the top of "NGL options" will change from "pdb:" to "opm:". Furthermore, the structure will automatically be aligned and embedded in a schematic lipid bilayer: two discs, red-OUT (extracellular/lumenal) and blue-IN (cytoplasmic).
Click on the "Rebuild Geometry" button - this will generate a coarse molecular surface that can be toggled on/off with the "Show Geometry used" checkbox
Next to "Show Beads", in the pull down menu, select the entry "0" if it's not already done
Dial the slider number of cluster to 10 (if it's already at 10, you can just click it) - this will apply the K-means algorithm on the atom positions to generate a 10-bead representative cluster.
in the comment section of the table for this ingredient you should see"opm", if not add it.

IgG

Final Check

In the recipe view click on myrecipe, this will show in the property view an overview of the recipe.
1. In the bottom panel, select all ingredients in the Recipe table. Click on the first row, and then shift-click on the last row. This will load all ingredients in the NGL View panel and give a quick preview of all ingredients at once.

In the "Recipe table" widget double click in the cell corresponding to the "ABCtransporter" row, "pdb" column. Enter the PDB id 1hzh.The "NGL View" window should update and load the structure in NGL, as well as updating the "NGL options" and "ingredient properties" panels
Click on the "Rebuild Geometry" button - this will generate a coarse molecular surface that can be toggled on/off with the "Show Geometry used" checkbox
Next to "Show Beads", in the pull down menu, select the entry "0" if it's not already done
Dial the slider number of cluster to 10 (if it's already at 10, you can just click it) - this will apply the K-means algorithm on the atom positions to generate a 10-bead representative cluster.

Export to cellPACK

The recipe is ready to be exported! In the gray command bar at the top, click:

Export->cellPACK recipe

Export->cellPACK-gpu recipe

This should save/download both files in your user Downloads folder. You can also find these recipes here:

myrecipe.json

myrecipe_serialized.json

Building the model - cellPACK-Blender

Step 1 Set Up

Start Blender. Click once outside of the splash screen to remove it. You should see a workspace laid out as in the figure below, with Tabs on the left edge, Viewport in the middle, and Outliner in the upper right. Resize the various windows as needed so you can see clearly - but for now, be careful not to do anything else or it might mess things up.

Disable the 3D Cursor, if you have not already done so. Click File>User Preferences>Input>3D View>3D View(Global)>Set 3D Cursor(clear the check box). Click the "Save User Settings" button on the bottom of the window so you don't have to do this every time you launch. Close the Preferences window.

In the Viewport you will see a cube and some other stuff. In the Outliner you will see a "Cube" object and some other stuff corresponding to the things in the Viewport. The "other stuff" is not important for this tutorial - just ignore it.

Delete the Cube by right-clicking on it in the Outliner, then clicking on "Delete".

Step 2 Load a recipe in autoPACK

Start autoPACK (push the button). A new tab named "Misc" containing the plugin interface will appear on the far left, and an (empty) object called "Welcome to autoPack" will appear in the Outliner.
Click on the Misc tab. To make space, close the "Register AP" panel by clicking the "Cancel" button at the bottom of the panel.
- In the "autoPACK" panel click File->"Load a recipe"
Browse to the file you exported earlier ("myrecipe.json") and load it by pressing "choose a file" button in the top right.
Once it is loaded, click on the "Pack" menu
In the "Build an autoPACK/cellPACK recipe for:" pull down menu select "Load"
Click "Start" - this will open a new panel called "myrecipe Filler v1.6". This panel is also known as the "Packing widget"
(Note - to get it to look like the image below, you would need to go to the command bar below the Viewport. To the right of the "Object Mode" dropdown is a small dropdown with a circular object on it. Click on it and select "Wireframe". Then zoom out with the scroll wheel to see the whole assembly.)

Step 3 Build the model

In the "PACKing Options" menu, leave the placeMethod as jitter (e.g. grid based collision), and the innerGridMethod as jordan3, but change the "Smallest ingredient packing radius override" to 15.0 (this is the resolution of the grid used for distance and overlapping - a larger value will speed up the packing, but make it less accurate).
In the "Recipe options" menu, change all "Density" values to 0 (if they're not already), and in the "+ this many ingredients" column:
- for ABCtransporter put 25
- for elongationFactor put 50
- for IgG put 100

Click "Clear PACK"
- Note: Before running the packing, toggle the system console (Window->toggle system console), on mac and Linux it is the terminal where you launched blender. The console will log the current progress of the packing. Press "return" if it doesn't update.
Click "PACK" at the bottom of the panel, and wait for the result (can take several minutes to compute)
Save the results: at the top of the "myrecipe Filler v1.6" panel, click the "File" dropdown, and select "Save Result". This will open the save dialog, and you can change the filename and location if you want. The results will be saved as a .json file with the bead representations, positions, and rotations of all ingredients, but not the geometries.
After the first Packing you can repack with different settings. Uncheck the "Rebuild the grid" checkBox in "PACKing Options" - building the grid takes time, and you already built it once for the first pack. Click "Clear Packing" at the bottom of the "myrecipe Filler v1.6" panel to remove your current packing (you might need to enlarge the window to figure out which button it is - there is a "Clear Recipe" button to the right of it). You can change the count for any ingredient, and then click PACK again to generate another model.

Building the model - real-time cellPACK-gpu prototype (only windows)

- download cellPACK-gpu for windows.

- unzip and run cellPACKgpu.exe

- browse to load the recipe you exported from mesoscope (myrecipe_serialized.json)

- interface help

Simulation of a model - MOLTEMPLATE-LAMMPS

LAMMPS is an extremely flexible and customizable molecular dynamics engine. Moltemplate is a general cross-platform text-based molecule builder for LAMMPS. Moltemplate was designed for inventing new kinds of complex coarse-grained toy models of molecules, molecular machines, and assemblies. However it is well suited for preparing realistic all-atom simulations as well. It supports a wide variety of existing force fields including: OPLS, AMBER(GAFF,GAFF2), COMPASS, MARTINI, SDK, LOPLS(2015), EFF, and TraPPE(1998), however it can be used to build molecules using any of the force fields (and atom styles ) available in LAMMPS, including new force fields created by modifying the LAMMPS source code. Molecules can be copied, combined, and linked together as building-blocks to define new molecules (hierarchically). Once built, individual molecules and subunits can be customized (atoms, bonds, and subunits can be moved and deleted). Moltemplate is currently interoperable with: VMD, PACKMOL, cellPACK, OVITO, and the ATB molecule database.

Cellpack2moltemplate has been developed for the purpose of simulating cellPACK models with an accurate simulation engine (LAMMPS).

We will demonstrate the current version (which is still in development) applied to a simple cellPACK model, as well as how to playback the simulation in the cellVIEW/cellPACK-gpu rendering engine. As a quick reference note, the pipeline is:

- Mesoscope -> recipe -> cellPACK -> model -> cellpack2moltemplate -> system -> moltemplate -> input -> LAMMPS

In the future cellpack2moltemplate will be directly integrated in cellPACK.

Andrew Jewett will then show some simulations done with Moltemplate and LAMMPS.

Painting a model - cellPAINT

CellPAINT is an evolving effort to bring mesoscale biology to the general public. Our initial version of cellPAINT was developed in 2D, and was intended to give a better understanding of the structural biology of the HIV virus. We have continued the development of cellPAINT as a 3D painting tool, using proteins as a palette. We will demonstrate the latest version of cellPAINT using an introductory recipe and a more advanced one.

To use your recipe in cellPAINT, in the sprite option generate a sprite with NGL or Illustrate. Then save cellPAINT recipe and sprites.