Controlling PyMol from afar

Do you keep downloading .pdb and .sdf files and loading them into PyMol repeatedly?

If yes, then PyMol remote might be just for you. With PyMol remote, you can control a PyMol session running on your laptop from any other machine. For example, from a Jupyter Notebook running on your HPC cluster.

Setup

You need to have pymol_remote installed on both the local and remote machine.

pip install pymol_remote

Usage

Start PyMol server on laptop First, start a PyMol server using pymol_remote. By default, it listens on port 9123.

pymol_remote

Create tunnel

Next, forward the remote port. To do this manually, choose a port to forward to, say 9123 again, and create an ssh tunnel for example.

ssh -R 9123:localhost:9123 buttensc@nagagpu04 -N -f -o ExitOnForwardFailure=yes

Optionally: Since I also use ssh to connect to the server, I added a RemoteForward entry to my ~/.ssh/config which will automatically do the port forwarding for me.

Host yourservername
    HostName yourservername.stats.ox.ac.uk
    RemoteForward 9123 localhost:9123

Setup PyMol session in notebook

Now, open a Jupyter Notebook on the remote server. In the notebook, setup the remote PyMol session using localhost as the IP address and the port chosen in the previous step.

from pymol_remote.client import PymolSession
cmd = PymolSession(hostname="127.0.0.1", port=9123)

Use PyMol remotely

That’s it! We can now control the remote PyMol session like we would a local session. For example, we can fetch a structure from the PDB and generate the protein’s surface.

# reset PyMol session
cmd.reinitialize()

# load entry 8TZX from the PDB
cmd.fetch("8TZX")

# show the protein with a white surface
cmd.hide("cartoon")
cmd.show("surface")
cmd.color("white", "polymer")

Now, let’s add a prediction stored on the machine running the Notebook:

with open("./model_output/top_prediction.sdf") as file:
  
    # read local file into buffer
    buffer = file.read()

    # load buffer into the remote PyMol session
    cmd.set_state(buffer, format="sdf", object="prediction")

We can manipulate the PyMol session via the user interface, the PyMol command line, or the Python API in the notebook.

Once we are happy, we can save the image: