AI agent guide for SAMSON Python scripting#

This page summarizes how AI coding assistants should use the SAMSON Python Scripting documentation. It is a retrieval guide, not a replacement for the task guides or the generated API reference.

Most important pages#

Start with these pages before drafting code:

Start scripting in SAMSON for the first embedded-console workflow.
Python scripting mental model for documents, nodes, selections, undo, and units.
Running actions for triggering SAMSON commands.
Selecting nodes for changing the active selection.
Getting nodes for retrieving nodes with NSL.
Building for creating molecular systems.
Units for physical quantities.
Examples for complete recipe scripts.
SAMSON Python API overview for common API entry points.

Common user goals#

User goal	Relevant documentation	Typical APIs
Run a SAMSON action	Running actions	`SAMSON.runCommand(...)`
Select atoms, residues, molecules, or paths	Selecting nodes, Getting nodes	`SAMSON.getNodes(...)`, `selectionFlag`
Inspect or modify a document	Working with documents and nodes	`SAMSON.getActiveDocument()`, `SBDocument`
Build atoms, bonds, and structural models	Building	`SBStructuralModel`, `SBAtom`, `SBBond`
Make changes undoable	Making operations undoable	`with SAMSON.holding(...):`, `SAMSON.hold(...)`
Use lengths, positions, times, or energies	Units	`SBQuantity`, `SBPosition3`
Adapt a complete script	Examples	Depends on the recipe.

Choosing commands, node retrieval, and direct API calls#

Use SAMSON.runCommand() when the user wants to trigger an existing SAMSON action by name, such as changing the view or running a named selection command.

Use SAMSON.getNodes() when the script needs nodes for further processing. getNodes returns a node indexer; it does not select nodes by itself.

Use direct API calls when the script needs to inspect or modify objects, including setting node flags, adding children, creating atoms, assigning colors, or exporting data.

Selection and NSL patterns#

Prefer NSL queries for retrieving existing nodes:

atoms = SAMSON.getNodes("node.type atom")
residues = SAMSON.getNodes("node.type residue")

When a script changes selection flags directly, wrap the changes in SAMSON.holding if users should be able to undo the selection operation.

Undoable operation pattern#

Use this pattern for document changes that should appear in SAMSON’s history:

with SAMSON.holding("Describe the operation"):
    SAMSON.hold(node)
    node.create()
    SAMSON.getActiveDocument().addChild(node)

Only hold nodes whose creation, destruction, or modification should be tracked by Undo / Redo.

Units and quantities#

SAMSON APIs often expect physical quantities rather than raw numbers. Prefer constructors such as:

distance = SBQuantity.angstrom(1.2)
position = SBPosition3(
    SBQuantity.angstrom(0.0),
    SBQuantity.angstrom(1.0),
    SBQuantity.angstrom(0.0),
)

Common pitfalls#

Do not claim snippets were executed in SAMSON unless they were actually run there.
Do not assume a document is open unless the page or user request says so.
Do not use getNodes when the user specifically asks to run a SAMSON command.
Do not use runCommand when the script needs returned nodes for processing.
Do not change selectionFlag directly without considering undo behavior.
Do not mix raw floats with SAMSON physical quantities where quantities are expected.
Do not edit generated Markdown, HTML, conf.py, or sphinx.log; edit source RST or exporter configuration.

Where to look in the API reference#

Use SAMSON Python API overview first. Then follow links to the generated reference for exact signatures and properties:

AI agent guide for SAMSON Python scripting

Contents