Getting started#

The Python Scripting extension in SAMSON provides Python bindings for the SAMSON API and an integrated Python console.

The Python bindings follow the same overall structure as the SAMSON SDK: classes have the same short names as in the SDK and functions keep the same names and parameters, except that some getter/setter pairs are exposed as Python properties where appropriate. This makes it easy to transfer code between Python and C++ with only minor modifications.

See also

SAMSON User Guide

SAMSON Developer Guide

Importing samson module#

The Python Scripting module has a flat structure: most classes are exposed directly in the module, with the main exception being the samson.SBQuantity sub-module that contains the available units.

Python bindings for the SAMSON API are already imported in the embedded Jupyter Qt Console in the following way:

import samson
from samson import *

So you don’t need to import anything and can directly use SAMSON classes, for example:

Using SAMSON commands#
# select ligands
SAMSON.runCommand("Ligands")
# apply Licorice to the current selection
SAMSON.runCommand("Licorice")
# clear the selection
SAMSON.runCommand("Deselect all")
Change the camera view#
# change the active camera's view using commands
SAMSON.runCommand("Top view")

# change the view directly via the active camera
# get the active camera
camera = SAMSON.getActiveCamera()
# change the view of the camera
camera.topView()
Clear selection in an undoable way#
activeDocument = SAMSON.getActiveDocument()
with SAMSON.holding('Clear selection'):
    activeDocument.clearSelection()

Getting help#

Apart from the online documentation, you can access help directly in the embedded Jupyter Qt Console:

  • help(SBColor) - prints the docstring in the console.

  • SBColor? - prints the docstring in the console without immediately flushing it; press q to exit.

  • SBColor.__doc__ - prints a special attribute __doc__ of modules, functions, classes, and methods.

If you have any questions, please, check the SAMSON forum for similar topics or post your question there.

Saving history#

You can save the history of commands and results in an HTML file by pressing Ctrl+S (on Win and Linux) or Cmd+S (on macOS) right in the terminal.

To see the history of input commands you can use:

%history

If you want to save commands in a Python file you can use the %save magic:

# saves commands from the input cells 1 through 5 to a file called filename.py
%save filename.py 1-5

Running scripts#

To run your own script, you can do the following:

import os

# change directory to the one which contains the file
os.chdir('/path/to/your/script/')

# run the file in the IPython's namespace (e.g., to have samson imported)
%run -i file.py

# or directly using IPython
from IPython import get_ipython
ipython = get_ipython()
# note that you might need to use quotes for the file name, e.g. if it contains spaces
ipython.run_line_magic("run", "-i \"/path/to/script.py\"")

Installing Python packages#

To install a Python package, go to Python Console > Edit > Manage packages and provide the package name and click Install.

The Python console uses pip internally, so you can specify the package version, if necessary, in the same way as when using pip.