biotite.interface.pymol

This package enables the transfer of structures from Biotite to PyMOL for visualization and vice versa, via PyMOL’s Python API:

• Import AtomArray and AtomArrayStack objects into PyMOL - without intermediate structure files.

• Convert PyMOL objects into AtomArray and AtomArrayStack instances.

• Use Biotite’s boolean masks for atom selection in PyMOL.

• Display images rendered with PyMOL in Jupyter notebooks.

Launching PyMOL

Library mode

The recommended way to invoke PyMOL in a Python script depends on whether a GUI should be displayed. If no GUI is required, we recommend launching a PyMOL session in library mode.

import biotite.interface.pymol as pymol_interface

pymol_interface.launch_pymol()

Usually launching PyMOL manually via launch_pymol() is not even necessary: When Biotite requires a PyMOL session, e.g. for creating a PyMOL object or invoking a command, and none is already running, PyMOL is automatically started in library mode.

GUI mode

When the PyMOL GUI is necessary, the PyMOL library mode is not available. Instead PyMOL can be launched in interactive (GUI) mode:

import biotite.interface.pymol as pymol_interface

pymol_interface.launch_interactive_pymol("-qixkF", "-W", "400", "-H", "400")

launch_interactive_pymol() starts PyMOL using the given command line options, reinitializes it and sets necessary parameters.

After that, the usual PyMOL commands and the other functions from Biotite are available.

Note that the PyMOL window will stay open after the end of the script. This can lead to issues when using interactive Python (e.g. IPython): The PyMOL window could not be closed by normal means and a forced termination might be necessary. This can be solved by using PyMOL’s integrated command line for executing Python.

Launching PyMOL directly

Note

This is not the recommended way to use PyMOL in the context of biotite.interface.pymol. Usage is at your own risk.

You can also launch PyMOL directly using the PyMOL Python API, that launch_pymol() and launch_interactive_pymol() use internally. In this case, it is important to call setup_parameters() for setting parameters that are necessary for Biotite to interact properly with PyMOL. Furthermore, the pymol_instance parameter must be set the first time a PyMOLObject is created to inform Biotite about the PyMOL session.

from pymol2 import PyMOL
import biotite.interface.pymol as pymol_interface

pymol_app = PyMOL()
pymol_app.start()
pymol_interface.setup_parameters(pymol_instance=pymol_app)
cmd = pymol_app.cmd

pymol_object = pymol_interface.PyMOLObject.from_structure(
    atom_array, pymol_instance=pymol_app
)

Common issues

As PyMOL is a quite complex software with a lot of its functionality written in C++, sometimes unexpected results or crashes may occur under certain circumstances. This page should provide help in such and similar cases.

Interactive PyMOL crashes when launched on MacOS

Unfortunately, the PyMOL GUI is not supported on MacOS, as described in this issue. The library mode launched by default should still work.

Interactive PyMOL crashes when launched after usage of Matplotlib

Interactive PyMOL will crash, if it is launched after a Matplotlib figure is created. This does not happen in the object-oriented library mode of PyMOL. Presumably the reason is a conflict in the OpenGL contexts.

Example code that leads to crash:

import matplotlib.pyplot as plt
import biotite.interface.pymol as pymol_interface

figure = plt.figure()
pymol_interface.launch_interactive_pymol()

‘cmd.png()’ command crashes in pytest function

pytest executes the test functions via exec(), which might lead to the crash. Up to now the only way to prevent this, is not to test the png() command in pytest.

Launching PyMOL for the first time raises DuplicatePyMOLError

For example the code snippet

import biotite.interface.pymol import cmd, launch_pymol

launch_pymol()

raises

biotite.interface.pymol.DuplicatePyMOLError: A PyMOL instance is already running

The reason:

If from biotite.interface.pymol import pymol or from biotite.interface.pymol import cmd is called, PyMOL is already launched upon import in order to make the pymol or cmd attribute available. Subsequent calls of launch_pymol() or launch_interactive_pymol() would start a second PyMOL session, which is forbidden.

To circumvent this problem do not import pymol or cmd from biotite.interface.pymol, but access these attributes via pymol_interface.pymol or pymol_interface.cmd at the required places in your code.

PyMOL is a trademark of Schrodinger, LLC.

Launching and resetting

launch_pymol	Launch PyMOL in object-oriented library mode.
launch_interactive_pymol	Launch a PyMOL GUI with the given command line arguments.
reset	Delete all objects in the PyMOL workspace and reset parameters to defaults.
setup_parameters	Sets PyMOL parameters that are necessary for Biotite to interact properly with PyMOL.
DuplicatePyMOLError

Object handling

PyMOLObject

A handle to a PyMOL object (PyMOL model), usually created by the static from_structure() method.

Structure conversion

to_model	Convert an AtomArray into a chempy.models.Indexed object.
from_model	Convert a chempy.models.Indexed object into an AtomArray.

Compiled Graphics Objects

draw_cgo	Draw geometric shapes using Compiled Graphics Objects (CGOs).
get_cylinder_cgo	Get the CGO for a cylinder.
get_cone_cgo	Get the CGO for a cone.
get_sphere_cgo	Get the CGO for a sphere.
get_point_cgo	Get the CGO for one or multiple points.
get_line_cgo	Get the CGO for a line following the given positions.
get_multiline_cgo	Get the CGO for one or multiple straight lines drawn from given start to end positions.

Combined shapes

draw_arrows	Draw three-dimensional arrows using Compiled Graphics Objects (CGOs).
draw_box	Draw a box using Compiled Graphics Objects (CGOs).

Display

show	Render an image of the PyMOL session and display it in the current Jupyter notebook.
play	Render an video of the PyMOL video frames and display it in the current Jupyter notebook.

Miscellaneous

ModifiedObjectError	Indicates that a atoms were added to or removed from the PyMOL object after the corresponding PyMOLObject was created.
NonexistentObjectError	Indicates that a PyMOL object with a given name does not exist.
RenderError	Exception that is raised when imagemagick or ffmpeg fails.
TimeoutError	Exception that is raised after time limit expiry in show().