Start scripting in SAMSON#

This short tutorial gives you a first working path through SAMSON Python scripting. It is intended for SAMSON’s embedded Python environment.

What you will do#

You will:

  • run a SAMSON command from Python;

  • access the active document;

  • select nodes with a command;

  • retrieve nodes for processing;

  • make a small undoable selection change.

Before you begin#

Open SAMSON and load or create a document. Some snippets below require nodes in the active document, for example atoms or ligands.

In the embedded Python Console, the samson module is already imported with:

Imports already available in the embedded Python Console#
import samson
from samson import *

Open the Python Console#

Use SAMSON’s embedded Python Console for quick commands and short experiments. For longer scripts, use the Code Editor described in Developing scripts.

Run your first commands#

The SAMSON.runCommand() function runs SAMSON commands and actions by name. The command names are the names you see in the SAMSON interface.

Run SAMSON commands from Python#
# change the active camera view
SAMSON.runCommand("Top view")

# select ligands in the active document
SAMSON.runCommand("Ligands")

# clear the current selection
SAMSON.runCommand("Deselect all")

See Running actions for more command examples and details about action names.

Get the active document#

Most scripts work with the active document: the document currently visible in SAMSON’s Document view.

Get the active document#
document = SAMSON.getActiveDocument()
print(document)

See Working with documents and nodes for more about documents, cameras, and nodes.

Select nodes#

You can use commands to select nodes directly. For example, the following command selects ligands, then clears the selection:

Select nodes with SAMSON commands#
SAMSON.runCommand("Ligands")
SAMSON.runCommand("Deselect all")

You can also select nodes with a Node Specification Language (NSL) expression by prefixing the expression with nsl::

Select atoms with NSL#
SAMSON.runCommand("nsl: node.type atom")

See Selecting nodes for selection actions, NSL selection, and direct selection flags.

Get nodes for processing#

When you want to process nodes in Python instead of just selecting them, retrieve them with SAMSON.getNodes(). It returns an SBNodeIndexer.

Retrieve atoms from the active document#
atomIndexer = SAMSON.getNodes("node.type atom")
print(len(atomIndexer))

for atom in atomIndexer:
    print(atom)

See Getting nodes for more examples of node retrieval and indexer usage.

Make an undoable change#

When a script changes document state directly, use SAMSON.holding so the operation appears in the SAMSON history and can be undone.

Select atoms in an undoable way#
atomIndexer = SAMSON.getNodes("node.type atom")

with SAMSON.holding("Select atoms"):
    SAMSON.getActiveDocument().clearSelection()
    for atom in atomIndexer:
        atom.selectionFlag = True

See Making operations undoable for the undo system and when to use SAMSON.holding.

Where to go next#