Building#
SAMSON documents have a hierarchical structure: each node has one and only one parent node (with the exception of documents, which have no parent), and possibly some children or references to other nodes.
You can create hierarchies of nodes and add them to a document using Python Scripting in SAMSON.
See also
User Guide: Node types
User Guide: Building molecules
User Guide: Documents
User Guide: Node Specification Language
Creating a structural model#
A structural model (SBStructuralModel) is the top structural parent node of all structural nodes.
So, if you want to add any other structural nodes (e.g., molecules, residues, atoms) into a document, then they should be added into a structural model or into one of its children depending on the hierarchical structure.
Note
Not any type of a node can be added into any node - there are hierarchical limitations. For example, a backbone and a side chain can anly be added into a residue, a molecule can be added only in a structural model, etc. Please see User Guide: Node types for more information on hierarchies of nodes.
The code below shows how to create a structural model and add it in the active documents in an undoable way:
# create an instance of a structural model
structuralModel = SBStructuralModel()
# set the structural model's name
structuralModel.name = 'Structural model'
# make the operation undoable
SAMSON.beginHolding("Add structural model")
# hold the node to make it creation undoable
SAMSON.hold(structuralModel)
# create the node
structuralModel.create()
# add the visual model to the active document
SAMSON.getActiveDocument().addChild(structuralModel)
# stop holding the undoable operation
SAMSON.endHolding()
When creating nodes that will be added to a document, it is necessary to make their creation undoable. For the sake of the undo mechanism we distinguish a construction of a node from its creation - a node can be constructed and used for computation without being created - the creation is needed if you want to add a node into a data graph/document. To make this operation undoable, it is necessary to use SAMSON.beginHolding() and SAMSON.endHolding() wrappers and hold the node before creating it using SAMSON.hold() (see the code above).
Note
If you construct a temporary node just for an internal use without adding it to a document then there is no need to create (SBNode.create()) it and no need to make it undoable.
Creating an atom#
The code below shows how to construct an atom (SBAtom) according to its element symbol and position and add it in a parent node.
# create two position vectors
position1 = SBPosition3(SBQuantity.nm(1.0), SBQuantity.nm(2.0), SBQuantity.nm(0.0))
position2 = SBPosition3(SBQuantity.nm(1.0), SBQuantity.nm(2.1), SBQuantity.nm(0.0))
# get an elementType from element symbol (C is for Carbon)
elementType = SAMSON.getElementTypeBySymbol('C')
# or you can use the element type directly
# elementType = SBElement.Carbon
# construct an atom with the given element type and position
atom1 = SBAtom(elementType, position1)
atom2 = SBAtom(elementType, position2)
# make the operation undoable
SAMSON.beginHolding("Add atoms")
# hold the node for undo/redo
SAMSON.hold(atom1)
SAMSON.hold(atom2)
# create an atom in SAMSON
atom1.create()
atom2.create()
# add an atom to the structural model
structuralModel.addChild(atom1)
structuralModel.addChild(atom2)
# stop holding the undoable operation
SAMSON.endHolding()
# center the active camera on the system
SAMSON.getActiveCamera().center()
Note
If you create multiple nodes, you can wrap the whole code within a single call of SAMSON.beginHolding() and SAMSON.endHolding() functions. In this way, it will be represented as a single operation in the history.
If you add nodes (e.g., atoms) to a node (e.g., a structural model) that later will be created, then you do not to hold (SAMSON.hold()) and create (SBNode.create()) each node separately - you need to do it only for the top node which will automatically hold and create its child nodes for you.
Creating covalent bonds#
You can create bonds (SBBond) between atoms as follows:
# create a double bond between atoms atom1 and atom2
bond = SBBond(atom1, atom2, 2.0)
# make the operation undoable
SAMSON.beginHolding("Add bond")
# hold the node for undo/redo
SAMSON.hold(bond)
# create the bond in SAMSON
bond.create()
structuralModel.addChild(bond)
# add the bond to a parent of one of the atoms
if atom1.getParent():
atom1.getParent().addChild(bond)
# stop holding the undoable operation
SAMSON.endHolding()
Or you can use SAMSON to create covalent bonds between atoms in a structural model based on the distances:
# make the operation undoable
SAMSON.beginHolding("Create covalent bonds")
structuralModel.createCovalentBonds()
# stop holding the undoable operation
SAMSON.endHolding()
The SBStructuralModel.createCovalentBonds() creates covalent bonds between atoms based on residue types, chemical component dictionary, and inter-atomic distances (it also accepts and additional margin for inter-atomic distances).
Or based on the residue types as well:
# make the operation undoable
SAMSON.beginHolding("Create covalent bonds")
# Create covalent bonds for the atoms belonging to the structural model
# according to the residue types, regardless of inter-atomic distances.
# If the bonds are already present, it sets the order of covalent bonds for the atoms
# belonging to the structural model according to the residue types.
structuralModel.createCovalentBondsByResidueType()
# stop holding the undoable operation
SAMSON.endHolding()
Adding hydrogens#
You can use SAMSON to add hydrogens to atoms. The code below shows how to add hydrogens to all atoms in the document.
# get an indexer of all atoms in the active document
atomIndexer = SAMSON.getNodes('node.type atom')
# make the operation undoable
SAMSON.beginHolding("Add hydrogens")
for atom in atomIndexer:
atom.addHydrogens()
# stop holding the undoable operation
SAMSON.endHolding()
Note
The addition of hydrogens is based on valences and requires covalent bonds to be already created.
You can also remove hydrogens from atoms:
# make the operation undoable
SAMSON.beginHolding("Remove hydrogens")
atom.removeHydrogens()
# stop holding the undoable operation
SAMSON.endHolding()
Minimizing systems#
You can run interactive minimization using SAMSON commands (see the Running actions section):
SAMSON.runCommand('Minimize')
This will launch the minimization in SAMSON - you can see the process in the Viewport.
Call this command once more to stop the interactive minimization.
Note
The minimization is applied either to the whole active document or to the selection in the active document depending on the minimization settings set in the Preferences > Minimize. You can also see other minimization settings there.
Examples#
Creation of a carbon nanotube fabric: replication, modification of positions