Python Scripting Cookbook

This command is used by info() to run a system command via bash shell. This is useful to access system information, for example about the machine one is running on:

i=run_command("uname -a")
print(i)
>>>Darwin neo.lan 24.3.0 Darwin Kernel Version 24.3.0: Thu Jan  2 20:24:22 PST 2025; root:xnu-11215.81.4~3/RELEASE_ARM64_T6041 arm64  

In the example below, we select all carbon alpha atoms and then print out their temperature B-factor values. No graphical representation is displayed.

s=fetch("1crn", showDefaultRep=False)
ca=select("name CA","ca")
for atom1 in ca.atoms:
      print(atom1.bfactor)

Loop over all carbon alpha atoms within 4.5 angstrom distance using a dynamic selection in a double loop, then annotate these distances. Not very useful per se, but illustrates the feature.

s=fetch("1crn", showDefaultRep=False)
showSelection("all_1crn", "trace")
ca=select("name CA","ca")
for atom1 in ca.atoms:
    tmp = select("name CA and within 4.5 atomid "+str(atom1.index+1),createSelection=False)
    for atom2 in tmp.atoms:
        if atom1 != atom2:
            annotateDistance(s.name,atom1.index+1,s.name,atom2.index+1)

In a double loop, we go over all chains in a model, and for each chain we iterate over all residues. We print summary information on number of residues per chain and number of atoms per residue.

s=fetch("1crn", showDefaultRep=False)
for chain in s.currentModel.GetChains():
    print("Chain with "+str(chain.residues.Count)+" residues encountered.")
    for residue in chain.residues:
        print("Residue with "+str(residue.atoms.Count)+" atoms encountered.")

UnityMol can be remote controlled through a ZeroMQ (ZMQ) network connection. ZeroMQ is a good choice if you need fast, asynchronous communication between your Python applications and are willing to worry about the details of messaging protocols.

More information:

• ZeroMQ Guide Chapter 1
• NetMQ

To manage the internal UnityMol server, you can activate it via

activateExternalCommands()

and shut it down via

disableExternalCommands()

Below is a simple and minimalistic skeleton to remote-control the ZMQ server we started in UnityMol from an external python script:

import zmq
socket = zmq.Context.instance().socket(zmq.REQ)
socket.connect("tcp://localhost:5555")
socket.send_string("fetch('1kx2')")

By default the server runs on port 5555 on the local machine localhost accessible via the tcp network protocol. We open a socket for communication, then we send the command to fetch the PDB-id 1kx2 from the PDB, which will be displayed with default settings. In this way we can feed UnityMol any commands it typically reads from a command python script.

In this github repository of a recent paper you will find the menu-spike1.py script that shows a more advanced usage of the above features, designing a custom menu to control a UnityMol instance. Below a screenshot illustrating the resulting menu.

A minimal example below to obtain a list of the currently defined selections in UnityMol. I the latest UnityMol version the ZMQ exchange now returns a json payload that contains three fields, success, a boolean about success or failure of the command execution, result, the actual result of the command as string, and stdout, the eventual stdout or log output as another string. Here we only use the result string:

import zmq
import json

socket = zmq.Context.instance().socket(zmq.REQ)
socket.connect("tcp://localhost:5555")

socket.send_string("getSelectionListString()")
result = json.loads(socket.recv().decode())["result"]
print(*[s.strip() for s in result.strip("[]").split(",") if s.strip()], sep="\n")

First, we establish a connection, then we get the result of the command getSelectionListString(), parse it to remove [,=]= and , characters, separating each selection name, and print these actual names for each selection.

A nice example is the implementation of a minimal python console to drive UnityMol outside the program. This was implemented in python with the ZMQ protocol. You can obtain the file by cloning the ScriptCollection git repository, or directly access the python-console.py script online. You will need the unitymol_zmq.py helper script to handle zmq connections, it is easily re-usable. With this script it is very easy to establish a connection and send commands. Here is boiler-plate code:

import unitymol_zmq
if unitymol_zmq.unitymol is None:
    unitymol_zmq.unitymol = unitymol_zmq.UnityMolZMQ()
    unitymol_zmq.unitymol.connect()
print(unitymol_zmq.unitymol.send_command_clean("ls()"))