Quickstart - a practical UnityMol tutorial

UnityMol is a molecular viewer that can be used in a standard desktop context or in a Virtual Reality (VR) context. For now, there are separate executables for the VR version and for the desktop version, but the same, identical code base is used.

UnityMol is also a molecular visualization platform to prototype and develop new molecular representations and custom interaction metaphores. It is developed mainly in C# in the Unity game engine.

Currently supported molecular input file formats are:

• PDB/mmCIF/GRO/Mol2/XYZ/SDF (structures)
• XTC for trajectory files
• OpenDX for potential maps

This tutorial gives a short introduction to UnityMol 1.1.2 in the form of a simplified documentation / tutorial.

UnityMol is currently based on a single main menu window with retractable sub-menus:

The top right button with an arrow hides the whole menu.

To make the python console appear (or disappear), you have to use the CTRL + <space bar> key combo, or use the top right arrow.

To use it, see the dedicated chapter discussing the .

• Every action done with UI buttons corresponds to a function or a set of functions of APIPython
• There are a LOT of options and commands that can be accessed via the console but are not possible from the UI

The console is using IronPython, a C# interpreter that compiles Python but also gives you access to C# objects. This means that you can call C# / Unity functions from the console like in: GameObject.Find("Directional Light")

UnityMol supports loading XTC trajectories using libxdrfile2. The first time a trajectory is loaded, a binary .offset file is created to store the position of each frame in the file. This allows to "jump" within the file without loading the whole trajectory in memory.

To load a trajectory, press the Load button from the Input menu and set the file filters to Trajectory files, or use the following syntax in the python interpreter:

loadTraj("structureName", "mypathToXTCFile.xtc")

By default, when using the Load button, UnityMol associates the trajectory data with the last loaded molecule.

The following sub-menu should be displayed under the loaded molecule UI row:

A similar menu is displayed when a molecule with several models is loaded. There are two ways to load a molecular file with several models. By default, UnityMol parses a PDB/mmCIF/GRO file with the setting modelsAsTraj = True, meaning that the first model is read and only the new positions of the next frames are stored. The second way is to store each model in a distinct UnityMolModel data structure.

UnityMol allows to have models with different numbers of atoms for the same molecule only if the modelsAsTraj flag is set to false.

The smooth button interpolates between 2 frames using a linear interpolation. Cubic interpolation uses 4 frames to interpolate between n-1 to n+2 frames. This feature can be enabled with:

last().xdr.cubicInterpolation = True

The average window button activates averaging all the frames between the current frame n and the n + WindowSize frames.

Note that smoothing and averaging should be fast because it is implemented using the C# Burst compiler, featuring a multi-threaded and SIMD accelerated computation.

Currently, UnityMol has 3 effects that you can activate in desktop mode:

UnityMol uses the CEAlign algorithm from here. It is an algorithm that performs well for low sequence similarity and still remains fast. It only uses alpha carbons to align the second argument (mobile) of the function cealign onto the first argument of the function (target).

As an example, load 2 proteins and display them as cartoon:

s1 = fetch("3eam", showDefaultRep=False)
s2 = fetch("3ei0", showDefaultRep=False)
show("c")
colorSelection(s1.ToSelectionName(), "c", Color.red)
colorSelection(s2.ToSelectionName(), "c", Color.blue)

You should obtain something like this:

Clicking on Run CEAlign from the Utils menu applies CEAlign on the 2 lastly loaded molecules. This GUI command is equivalent to

cealign(s1.ToSelectionName(), s2.ToSelectionName())

In the example given above, the result of the alignment is shown below.

You can show the bounding box of the loaded molecule by doing:

showBoundingBox("structureName")

It can be hidden again with hideBoundingBox("structureName").

When loading a protein with load() or fetch(), the default behaviour is to use the secondary structure information from the file and use the DSSP algorithm when there is none. You can force DSSP to be run:

fetch("1kx2", forceDSSP=True)

You can run DSSP on a loaded molecule by doing:

switchSSAssignmentMethod("structureName", forceDSSP=True)

There are several types of annotation in UnityMol to add labels, objects, lines and measurements to atoms. To add a transparent sphere around an atom:

annotateAtom("structureName", atomId)

To add a transparent sphere not attached to an atom, use

annotateSphere(worldP=Vector3(0,0,0), scale=1.0)

You can also add some label to an atom:

annotateAtomText("structureName", atomId, "My text")

or not attached to an atom:

annotateWorldText(Vector3(0,0,0), 1.0, "My text", Color.white)

To add text in 2D, you can use

annotate2DText(screenP=Vector2(0.5, 0.5), scale=1.0, text="My text", textCol=Color.white)

where the screen position is defined by (0,0) = bottom-left and (1,1) = top-right.

To add a line:

annotateLine("structureName", atomId, "structureName2", atomId2)

and not attached to an atom:

annotateWorldLine(Vector3(0,0,0), Vector3(3,0,0), 1.0, Color.white)

Measurements are using annotations to display lines and text on atoms. To make such measurements in desktop mode:

• press M and click on atoms to compute a distance/angle/torsion angle based on the setting of UnityMolMain.measureMode
• Clicking on the Measurement mode button in the Utils menu cycles through the modes
• The button calls the setMeasureMode() function to change UnityMolMain.measureMode. The command syntax is setMeasureMode(mode) where mode is
  • 0 = distance,
  • 1 = angle,
  • 2 = torsion angle

In VR, pressing the touchpad button while aiming the target atom should trigger measurements.

You can also play a sonar sound at a position in the scene to localize an atom or an object. Achieve this using the playSoundAtPosition(Vector3(10,0,0)) command.

Connection to a running simulation using the IMD protocol is established via the IMD menu. You can also call the corresponding function from the console:

connectIMD("structureName", "127.0.0.1", 8888)

for a simulation running on the localhost on the 8888 port. Disconnection using the console:

disconnectIMD("structureName")

By default, UnityMol uses the last loaded molecule when clicking on the IMD connect button.

During IMD, you can grab an atom or several atoms by click & dragging the mouse in desktop or the controller in VR.

The IMD protocol is implemented using MDDriver since UnityMol 1.1.2.

The UnityMol team collaborated with the Levitt lab at Stanford University to build an interactive docking mode in UnityMol, available in VR. It uses the AMBER forcefield to interactively compute the potential energy of the system. For more information please read .

One can export the current representations of a structure using one of these functions:

exportRepsToOBJFile("structureName", "outputpath.obj")

or

exportRepsToFBXFile("structureName", "outputpath.fbx")

• Note that this implementatiom currently ignores point, hbond and bond-order representations
• For HyperBalls representations, a custom algorithm extracts a mesh based on current hyperballs parameters, this approach can lead to a mesh that is slightly different from the actual representations in UnityMol. It also produces large meshes.

The file in FBX format is a binary file that is lighter than the OBJ text file format.

UnityMol has a command line interface with a few supported arguments:

• -d <directoryPath>: change the current directory to the one in <directoryPath>.
• -i <filename1> [<filename2>,...]: load one or several files supported by UnityMol.
• -v or --version: print the UnityMol version.
• -r or --remoteControl: Start Unitymol with a TCP Server listening to receiving external commands.
• -c or --commons: Load automatically the python module UnityMolCommons.py found in Streaming Assets.

You can directly load a molecular file or a command file (previously saved from UnityMol or edited as a custom script) when launching UnityMol from a terminal:

./UnityMol -i /path/to/UMolState.py

The above executes the UMolState.py script.

Below an example loading two structures, with trajectory data information for the second one:

./UnityMol -i /path/to/1kx2.pdb /path/to/1bl8.pdb /path/to/1bl8_traj.xtc

To fetch a PDB file from the internet when starting UnityMol you can do:

./UnityMol -i 3eam

You can also set the working directory with the -d flag, to easily load local files with the following syntax:

./UnityMol -d /path/to/folder

If you need help or have any question regarding UnityMol and it's usage, please send an email to unitymol at gmail.com. We are also active on Twitter/X as @UnityMol.