Python scripting mental model#

This page summarizes the main ideas behind Python scripting in SAMSON. Use it when you want to choose the right scripting approach before reading the detailed how-to guides.

SAMSON, documents, and nodes#

SAMSON stores molecular systems, visual models, cameras, simulators, and other objects in documents. Each document contains a data graph made of nodes. Many scripts start from the active document, then retrieve, select, create, or modify nodes.

Simplified document structure#
SAMSON
  active document
    data graph
      structural models
        molecules
          residues
            atoms and bonds
      visual models
      cameras
      simulators
      paths, labels, notes, folders, files

See Working with documents and nodes for document and node basics, and Building for creating structural nodes.

Common scripting choices#

Goal

Use

Read next

Run an existing SAMSON menu command

SAMSON.runCommand(...)

Running actions

Select nodes with NSL

SAMSON.runCommand("nsl: ...")

Selecting nodes

Retrieve nodes for Python processing

SAMSON.getNodes(...)

Getting nodes

Modify selection manually

node.selectionFlag = True

Selecting nodes

Make direct document changes undoable

with SAMSON.holding(...):

Making operations undoable

Work with distances, positions, and other physical values

SBQuantity and physical vector types

Units

Commands, selections, and node retrieval#

Use SAMSON.runCommand() when you want to trigger an existing SAMSON action by name, for example a command available in a menu. Some commands operate on the current selection, and some operate on the active document when the selection is empty.

Use SAMSON.runCommand("nsl: ...") when your goal is to select nodes with a Node Specification Language expression. Use SAMSON.getNodes() when your goal is to retrieve nodes into Python for iteration, filtering, printing, or further API calls.

Direct API changes and undo#

Commands run through SAMSON.runCommand() often manage undo internally. When your script directly changes document state, wrap the operation in SAMSON.holding when the change should appear in the SAMSON history.

Common examples include setting selectionFlag, changing node properties, creating nodes, or adding nodes to a document. See Making operations undoable for the undo workflow.

Units and physical quantities#

SAMSON uses typed physical quantities for many values, such as positions, distances, velocities, energies, and forces. When an API expects a physical value, use samson.SBQuantity constructors or the corresponding physical vector types instead of raw floats.

See Units for unit constructors and quantity examples.

Common assumptions in examples#

Most guide examples assume:

  • SAMSON is running and the code is executed in the embedded Python environment;

  • an active document exists when the script accesses SAMSON.getActiveDocument();

  • command behavior may depend on the current selection or active document;

  • node retrieval with SAMSON.getNodes() returns an SBNodeIndexer;

  • direct document changes should be wrapped in SAMSON.holding when undo is expected;

  • physical values should use SAMSON quantity types where the API expects them.