Getting started#

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

Python bindings for the SAMSON API are done in the same structure as the SAMSON SDK: classes have the same short names as in the SDK and functions are exposed with the same names and parameters except for some getter/setter functions that are exposed as class properties where possible. This makes it possible to easily trasnfer your code between Python and C++ with minor modifications.

See also

SAMSON User Guide

SAMSON Developer Guide

Importing samson module#

The Python Scripting module has a flat structure having all the classes directly in the module and no additional sub-modules apart from the samson.SBQuantity sub-module that contains all 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()
SAMSON.beginHolding('Clear selection')
activeDocument.clearSelection()
SAMSON.endHolding()

Getting help#

Apart from the online documentation, you can see the help in the embedded Jupyter Qt Console with auto-complete and as follows:

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

  • SBColor? - prints the docstring in the console but does not not flush it, to exit press ‘q’.

  • 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 may 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.