Python bindings for the SAMSON API are imported into the embedded Python console in the following way:

import samson as sam
from samson.Facade import SAMSON        # SAMSON Facade - main interface of SAMSON
from samson.DataModel import Quantity   # Quantities: length, mass, time, etc
from samson.DataModel import Type       # Types: position3, etc


Working with the module

Python bindings for the SAMSON API are done in the same tree-like structure as the SAMSON SDK itself. So, to create, for example, a color object one can do:

sam.DataModel.Type.Color(128, 64, 55, 255)  # RGB color with alpha channel
# or import submodule 'Type'
from samson.DataModel import Type
c = Type.Color(128, 64, 55, 255)            # RGB color with an alpha channel                                        # returns the red component

Getting help

Apart from the online documentation, you can see the help in the embedded Jupyter Qt console:

from samson.DataModel import Type
help(Type.Color) # this will show the docstring as an output in the terminal
Type.Color?      # this will show the docstring in the terminal but it will not flush it as an output, to exit press 'q'

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

Working with nodes in data graph

SAMSON maintains the information about models, simulators, etc., in a data graph.

To select different types of nodes from the data graph (e.g., molecules and atoms) you can use the Node Specification Language (NSL) from the SAMSON API and getNodes function either from the SAMSON interface class or applied to a specific node. The function getNodes returns a node indexer which is basically a list of nodes.

indexer1 = SAMSON.getNodes('n.type molecule')     # returns all molecule nodes
indexer2 = indexer1[0].getNodes('n.type atom')    # returns all atom nodes within the first molecule
indexer3 = SAMSON.getNodes('Hydrogen')            # returns all hydrogens
indexer4 = SAMSON.getNodes('H linking O')         # returns all hydrogens bonded to oxygen atoms
indexer5 = SAMSON.getNodes('"CA" within 5A of S') # returns all nodes named "CA" that are within 5 angstrom of any sulfur atom

You can go through an indexer like through a list:

indexer = SAMSON.getNodes('n.t a')                # returns all atom nodes
indexer.size                                      # returns size of the indexer
indexer[-1]                                       # prints information on the last atom in the indexer
for node in indexer:
    # do something
    node                                          # prints info on the node
# usage of list comprehensions:
indexer = SAMSON.getNodes('n.t a')                # returns all atom nodes
l = [atom.getX().nm for atom in indexer]          # constructs a list of x-coordinates of atoms in nanometers

You can delete or add a node from the indexer, or check if it is present in it:

indexer = SAMSON.getNodes('n.t a')                # get all atom nodes
a0 = indexer[0]                                   # get the first atom from the indexer
indexer.removeNode(a0)                            # remove the atom a0 from the indexer
indexer.hasNode(a0)                               # check if the indexer has the atom a0
indexer.addNode(a0)                               # add a0 back to the indexer

The next example shows a simple use of the NSL, nodeIndexer, and how to make changes to node attributes.

molecule_indexer = SAMSON.getNodes('n.type molecule')  # return all molecule nodes, see Node Specification Language
molecule_indexer[0]                                    # print name of the 1st molecule
atom_indexer = molecule_indexer[0].getNodes('n.t a')   # get atoms in a particular molecule
a0 = atom_indexer[0]                                   # get the 1st atom in atom_indexer
a0.type                                                # return type of the node
a0                                                     # print information on the node
a0.selectionFlag = True                                # select an atom: it will be higlighted
a0.atomicWeight                                        # return atomic weight of an atom
a0.getPosition()                                       # return position of an atom
a0.setPosition(a0.getPosition() + Type.position3(,, # shift the position of the chosen atom by 100 picometers in x-direction

Importing and exporting

Let us import a molecule, apply some random perturbations and export the result. To be able to import/export from/to some formats (pdf, xyz, mol2) two SAMSON Elements should be installed: Basic importers and Basic exporters.

import numpy as np
SAMSON.importFromFile('/path/to/molecule/2AZ8-IA.pdb')        # import molecule from .pdf, .xyz, .mol2, .samx, and other supported formats
# apply some random perturbations to atoms of the imported molecule
for a in SAMSON.getNodes('n.t a'):
    a.setX(a.getX() + Quantity.length(10.0 * np.random.randn(1)))
    a.setY(a.getY() + Quantity.length(10.0 * np.random.randn(1)))
    a.setZ(a.getZ() + Quantity.length(10.0 * np.random.randn(1)))
SAMSON.exportToFile('/path/to/molecule/2AZ8-IA-modified.samx') # export data into samx format or other supported formats, e.g. pdb, xyz

Making history: holding

History in SAMSON allows one to undo some operations. To do so, one needs to wrap an undoable code using the next commands: SAMSON.beginHolding(‘string to be added into History’) and SAMSON.endHolding().

SAMSON.beginHolding('select residues')    # begin holding
indexer = SAMSON.getNodes('n.t r')        # return all residue nodes 
for n in indexer: n.selectionFlag = True  # set selectionFlag to True for nodes in the indexer
SAMSON.endHolding()                       # end holding

This will create an undoable operation in the history.

Getting active Document, Camera, etc

To access the active Document or the active camera:

document = SAMSON.getActiveDocument() # return the active document
camera = SAMSON.getActiveCamera()     # return the active camera
camera.topView()                      # change the view of the camera

Saving history

You can save the history of commands and results in an HTML file by pressing Ctrl+S or Command+S right in the terminal.

To see the history of input commands you can use


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

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

Running scripts

To run your own script you may do the following:

import os
os.chdir('/path/to/your/script/')    # change directory to the one which contains the file
%run -i                      # run the file in the IPython's namespace (e.g., to have samson imported)

Comments are closed.