SAMSON Python Scripting

Automate molecular modeling in SAMSON with Python.

The Python Scripting extension in SAMSON provides Python bindings for the SAMSON API and an integrated Python console. It gives you access to most of the SAMSON SDK so that you can automate SAMSON workflows with Python.

Python bindings for the SAMSON API follow the same structure as the SAMSON SDK: classes have the same short names as in the SDK and functions are exposed with the same names and parameters, except for some getter/setter functions that are exposed as class properties where possible. This makes it possible to transfer code between Python and C++ with minor modifications.

The Python console in SAMSON comes with an integrated Jupyter Qt Console.

Note

This version of the Python bindings is for SAMSON SDK 2026 R1.

Python bindings are done thanks to pybind11 (pybind11 license).

What you can do

Use Python scripting in SAMSON to:

• run SAMSON commands and actions;

• select and retrieve nodes with the Node Specification Language (NSL);

• inspect and modify atoms, molecules, documents, cameras, and other nodes;

• build molecular systems programmatically;

• import and export files and trajectory frames;

• colorize, visualize, render, and animate molecular models;

• use SAMSON AI and the Code Editor to create and run scripts;

• create simple dialogs or more advanced Qt-based GUIs.

Start here

If you are new to SAMSON Python scripting, start with the short tutorial: Start scripting in SAMSON. Then continue with:

• Getting started for imports, help, command history, scripts, and package installation;

• Python scripting mental model for the main concepts behind commands, documents, nodes, selections, undo, and units;

• Developing scripts for SAMSON AI, the Code Editor, embedded scripts, and GUIs;

• Examples for complete scripts grouped by task;

• API overview for common entry points before you browse the full API reference.

Popular tasks

• Run a SAMSON command.

• Select atoms, residues, molecules, or other nodes.

• Get nodes with NSL.

• Make document changes undoable.

• Build molecular systems.

• Import and export files or trajectories.

• Render images.

Documentation

The Python Scripting Guide is organized by the way users usually work: first-run onboarding, core concepts, task guides, examples, API reference, and release information.

Start here

• Start scripting in SAMSON
  • What you will do
  • Before you begin
  • Open the Python Console
  • Run your first commands
  • Get the active document
  • Select nodes
  • Get nodes for processing
  • Make an undoable change
  • Where to go next
• Getting started
  • Importing samson module
  • Getting help
  • Saving history
  • Running scripts
  • Installing Python packages
  • Where to go next
• Developing scripts
  • Using SAMSON AI
  • Using Code Editor
  • Embedding Python Scripts
  • Installing Python packages
  • GUI

Core concepts

• Python scripting mental model
  • SAMSON, documents, and nodes
  • Common scripting choices
  • Commands, selections, and node retrieval
  • Direct API changes and undo
  • Units and physical quantities
  • Common assumptions in examples
  • Related API
• Working with documents and nodes
  • Documents
  • Common operations
  • Moving around
  • Working with nodes
  • Common mistakes
• Units
  • Do / Don’t
• Making operations undoable

How-to guides

• Running actions
  • Running actions by name
  • Selecting nodes using runCommand and NSL
  • Choosing commands, selections, and node retrieval
  • Running actions by UUID
• Selecting nodes
  • Select using actions
  • Select using NSL
  • Select via nodes
  • Clear selection
  • Selection examples
  • Common mistakes
• Getting nodes
  • Common mistakes
• Importing and exporting
• Building
  • Creating a structural model
  • Creating an atom
  • Creating covalent bonds
  • Adding hydrogens
  • Minimizing systems
  • Examples
  • Common mistakes
• Colorizing nodes
  • List of color schemes
  • Apply color
  • Apply color from color palette
  • Apply color scheme
  • Apply a color scheme with a color palette
• Visualizing
  • Applying visual models
  • Applying visual presets
• Presenting and animating
  • List of available animations
  • How to create a presentation
  • How to create an animation
  • Exporting a movie
• Rendering
  • Rendering effects
  • Render presets
  • Rendering using Cycles
• Introspection: using extensions
  • Getting proxies
  • Calling functions

Examples and recipes

• Examples
  • Building systems
  • Colorization and visualization
  • Processing and analysis
  • Selections
  • Animations and export
  • Simulation and external packages
  • Apps and GUIs
  • Contributing examples

AI assistant support

• AI agent guide for SAMSON Python scripting

API reference

The Python Scripting API reference is subdivided into groups that correspond to the SAMSON SDK Organization.

API reference

• SAMSON Python API overview
  • Common API entry points
  • Choosing an entry point
  • API reference map
• Core
  • Class
  • Container
  • Meta
  • Reference
• Data Model
  • Asset
  • Color Scheme
  • Data Graph
  • Document
  • Palette
  • SBQuantity
  • Type
  • Visualization
• Facade
  • SAMSON
• GUI
  • Action
• Modeling
  • Dynamical Model
  • Element
  • Interaction Model
  • Model
  • Property Model
  • Structural Model
  • Visual Model
• Simulation
  • Neighbor Search
  • Simulator
  • State Updater

Release notes and versions

• Changelog
• Available versions

For AI assistants

The AI agent guide summarizes the most important pages, API choices, undo patterns, NSL usage, and common pitfalls for coding assistants. The generated llms.txt file provides a compact map of the Python Scripting Guide and links to per-page Markdown files. The generated llms-full.txt file provides a full text export of the guide and API reference.

Site files

Privacy Policy

Terms of Use