Examples

This gallery collects practical SAMSON Python API recipes. Use it to find a script close to the task you want to automate, then open the recipe page for the complete code and notes.

Building systems

Recipe	Use when	Input	Output	Difficulty	APIs used
Building a decane molecule	You want to create atoms and bonds programmatically.	An active document.	A structural model with a decane-like chain.	Beginner	SBStructuralModel, SBAtom, SBBond, SAMSON.holding
Create atoms on a sphere	You want to generate a simple geometric atom distribution.	An active document.	A structural model populated with carbon atoms on a sphere.	Beginner	SBStructuralModel, SBAtom, SBPosition3, SBQuantity
Create a carbon nanotube fabric	You want a larger procedural construction workflow.	A nanotube model or nanotube creator workflow.	A woven carbon nanotube fabric.	Advanced	SBStructuralModel, SBAtom, SBPosition3, SBQuantity

Colorization and visualization

Recipe	Use when	Input	Output	Difficulty	APIs used
Colorize atoms by position	You want a spatial color gradient.	Atoms in the active document.	Atom colors based on X coordinates.	Beginner	SAMSON.getNodes, SBColor, SBPalette
Colorize atoms by velocity along path	You want to visualize motion along a path.	A trajectory path and atoms.	Atom colors based on velocity norm.	Intermediate	SBPath, SBPalette, SAMSON.holding
Visualize coarse-grained systems	You want to colorize coarse-grained nodes by names or types.	Coarse-grained nodes in the active document.	Group or atom colors that reveal coarse-grained structure.	Intermediate	SAMSON.getNodes, SBPalette, SAMSON.holding
Colorize connected components by molecular weight	You want color to encode connected-component mass.	Molecules or connected components.	Component colors based on molecular weight.	Intermediate	SAMSON.getNodes, SBNodeIndexer, SBPalette

Processing and analysis

Recipe	Use when	Input	Output	Difficulty	APIs used
Compute RMSD between two molecules	You want to compare two superimposed molecules.	Two molecule nodes with comparable atoms.	RMSD values printed in angstroms.	Intermediate	SAMSON.getNodes, SBQuantity, atom positions
Compute bond lengths along paths	You want bond-length statistics over trajectory frames.	A path and bonds in the active document.	Min, mean, and max bond lengths plotted over frames.	Intermediate	SBPath, SBBond, matplotlib
Compute interatomic distances along path	You want minimum atom distances over trajectory frames.	A path and atoms in the active document.	Minimum interatomic distances plotted over frames.	Advanced	SBPath, SBParticleSystem, SBNeighborSearchParticleSystemGrid

Selections

Recipe	Use when	Input	Output	Difficulty	APIs used
Select atoms and bonds by location	You want to select nodes from geometric criteria.	Atoms and bonds in the active document.	Selected atoms and bonds between two X positions.	Beginner	SAMSON.getNodes, SBNodeIndexer, selectionFlag
Select connected components by molecular weight	You want reusable selection logic for connected components.	Molecules or connected components.	Selected components that match the mass criteria.	Intermediate	SBNodeIndexer, SAMSON.holding, selectionFlag

Note

Select connected components by molecular weight and Dialog: select connected components by molecular weight intentionally use the same sample script. The first entry is listed with selection recipes; the dialog entry is listed with GUI recipes because it focuses on presenting the workflow through a dialog.

Animations and export

Recipe	Use when	Input	Output	Difficulty	APIs used
Presentation: play path	You want to animate a path inside a presentation.	A path in the active document.	A presentation that plays the path.	Intermediate	SBPath, presentations, SAMSON.processEvents
Create animations and movies without presentations	You want to record path or camera animations from Python.	A path or camera-ready document.	Image sequence or movie output.	Intermediate	imageio, moviepy, SAMSON.processEvents
Export trajectory frames	You want files for each frame of a trajectory.	A path and structural models.	PDB or XYZ files for trajectory frames.	Intermediate	SBPath, SAMSON.exportToFile, SAMSON.getNodes

Simulation and external packages

Recipe	Use when	Input	Output	Difficulty	APIs used
Examples of usage of ASE package	You want to combine SAMSON structures with ASE workflows.	ASE installed in SAMSON’s Python environment.	Optimized structures or simulation results.	Advanced	ase, SAMSON.importFromFile, SAMSON.getNodes

Apps and GUIs

Recipe	Use when	Input	Output	Difficulty	APIs used
Embedded app: a simple GUI with buttons	You want a small embedded PySide6 interface in SAMSON.	SAMSON’s embedded Python environment with PySide6.	A GUI with buttons that run SAMSON commands.	Intermediate	PySide6, SAMSON.runCommand, embedded apps
Dialog: select connected components by molecular weight	You want user-adjustable inputs before selecting components.	Molecules or connected components.	A dialog-driven selection workflow.	Intermediate	PySide6, SBNodeIndexer, SAMSON.holding

Contributing examples

When adding a new example, prefer a small reusable recipe with:

• a clear title and .. meta:: description;

• a short purpose statement and prerequisites;

• the script or a .. literalinclude:: of a sample file;

• the expected result after running it;

• a short note on how to adapt the script;

• the main SAMSON Python APIs used.

Keep scripts deterministic when possible. If an example requires a document, selection, path, plugin, external package, or local file, state that before the code block.