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 yourservername -N -f

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 file 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: