SAMSON Python API overview

Use this page as a bridge between task-oriented guides and the generated Python API reference. Start from the guides when you want a workflow; use the API pages when you need exact classes, functions, properties, and signatures.

Common API entry points

API	Use for	Related guide
SAMSON.runCommand()	Triggering SAMSON commands and actions by name.	Running actions
SAMSON.getNodes()	Retrieving nodes from the active document with NSL.	Getting nodes
SAMSON.getActiveDocument()	Accessing the active document before inspecting or modifying nodes.	Working with documents and nodes
SAMSON.getActiveCamera()	Accessing and adjusting the active camera.	Working with documents and nodes
SAMSON.holding	Making document changes undoable.	Making operations undoable
samson.SBNodeIndexer	Working with node collections returned by NSL queries and selection APIs.	Getting nodes
samson.SBNode	Understanding shared node behavior such as names, flags, parents, children, and lifecycle.	Python scripting mental model
samson.SBDocument	Managing document contents and selected nodes.	Working with documents and nodes
samson.SBStructuralModel	Creating or organizing structural nodes.	Building
samson.SBAtom	Creating, inspecting, selecting, or editing atoms.	Building
samson.SBBond	Creating or processing bonds between atoms.	Building
samson.SBColor	Assigning colors and working with RGBA values.	Colorizing nodes
samson.SBQuantity	Creating physical quantities with units.	Units

Choosing an entry point

Goal	Start with	Notes
Run an operation available in the SAMSON interface	SAMSON.runCommand()	Commands are UI actions and depend on command names.
Find atoms, residues, molecules, paths, or other nodes	SAMSON.getNodes()	Use NSL when you need nodes for further processing.
Change selection state directly	samson.SBNode.selectionFlag	Wrap direct selection changes in SAMSON.holding when the operation should be undoable.
Add new nodes to the active document	samson.SBStructuralModel, samson.SBAtom, SAMSON.holding	Create nodes, hold them for undo, and add them to a valid parent.
Work with lengths, positions, energies, or times	samson.SBQuantity	Prefer quantity constructors such as SBQuantity.angstrom(...) over raw floats.

API reference map

• SAMSON contains the high-level SAMSON functions used in most scripts.

• SBNode and SBNodeIndexer cover common node and node-collection behavior.

• SBDocument and SBCamera cover documents and cameras.

• SBStructuralModel, SBAtom, SBBond, SBMolecule, and SBResidue cover molecular structures.

• SBQuantity covers physical units and quantities.

• SBColor and SBPhysicalVector3 cover colors and physical vectors.

See also

Start scripting in SAMSON

Python scripting mental model

Examples