SAMSON

SAMSON#

This sub-module is the main interface to SAMSON API. You can access some of SAMSON functionality directly from this sub-module, for example:

activeDocument = SAMSON.getActiveDocument()

See also

SAMSON SDK: SAMSON

This class is the main interface of SAMSON. It acts as a facade that centralizes and exposes other functions from the SAMSON API to make it easy for developers to interact with SAMSON, the data graph, etc. All functions in this class are static.

samson.SAMSON.askUser(*args, **kwargs)#

Overloaded function.

askUser(dialogTitle: str, dialogText: str) -> bool

Asks a question to the user with a message in a modal pop-up dialog.

Parameters:

dialogTitle (str) – A title of the pop-up dialog.
dialogText (str) – A text in the pop-up dialog.

Returns:

True if the user clicked OK, False if the user clicked Cancel.

Return type:

bool

Examples

>>> SAMSON.askUser('Error', 'Caught an error during the execution.\nProceed?')

See also

informUser

askUser(dialogTitle: str, labelText: str, text: str, monospaceFont: bool) -> bool

Asks a question to the user with a message in a modal pop-up dialog.

Parameters:

dialogTitle (str) – A title of the pop-up dialog.
labelText (str) – A text of the message label.
text (str) – A text in the plain text edit.
monospaceFont (bool) – Whether the text should be shown using a monospace font or not.

Returns:

True if the user clicked OK, False if the user clicked Cancel.

Return type:

bool

Examples

>>> SAMSON.askUser('Error', 'Caught an error during the execution.\nProceed?', 'Error message...', True)

See also

informUser

samson.SAMSON.beginHolding(name: str) → None#

Begins holding.

Parameters:: name (str) – A name of the operation, it will be shown in the History.

Examples

Make the selection of molecules undoable:

>>> SAMSON.beginHolding('Select nodes')
>>> nodeIndexer = SAMSON.getNodes('node.type molecule')
>>> for node in nodeIndexer:
...     node.selectionFlag = True
>>> SAMSON.endHolding()

samson.SAMSON.canImportFromFile(fileName: str) → bool#

Returns true when the files can be imported.

Parameters:: fileName (str) – A path to the file

samson.SAMSON.captureViewportToFile(filename: str, width: int, height: int, transparentBackground: bool = False, usePathTracing: bool = False, showProgressBar: bool = True) → None#

Captures the viewport into file. The image format is based on the file extension.

Parameters:

filename (str) – The file path.
width (int) – The width of the image.
height (int) – The height of the image.
transparentBackground (bool, default=False) – Whether the viewport background should be transparent or not.
usePathTracing (bool, default=False) – Whether to use path tracing.
showProgressBar (bool, default=True) – Whether to show the progress bar when capturing, might be useful when using path tracing.

Examples

Capture the current viewport in a file.

>>> SAMSON.captureViewportToFile(filename = '/home/user/test.png',
>>>     width = 1200, height = 800)

samson.SAMSON.countNodes(*args, **kwargs)#

Overloaded function.

countNodes(selectionString: str = ‘*’, visitString: str = ‘*’, includeDependencies: bool = False) -> int

Counts nodes in the active document, based on the provided selection filter selectionString and other parameters.

This function traverses the active document’s sub-tree for which a predicate based on the visitString is True (depth-first), and stores counts the nodes for which the selectionString is True. Precisely, if the predicate based on the visitString returns false, the node is not visited, and neither are its descendants. If the predicate based on the visitString returns True, the node is visited, and this visit predicate will be used to decide whether its children are visited or not. Note that the node itself must satisfy the predicate based on the visitString else nothing is visited.

When includeDependencies is True, the function also counts nodes that are not descendants of this node, but are dependencies nonetheless. For example, in a SBBond, the two atoms connected by the bond are not children of the bond, but are still dependencies of the bond. Hence, provided they satisfy the selectionString and visitString, they are counted if includeDependencies is True.

Parameters:

selectionString (str, default='*') – A Node Specification Language expression (SAMSON API: Node Specification Language) that describes what nodes should be selected from the active document.
visitString (str, default='*') – A Node Specification Language expression (SAMSON API: Node Specification Language) that describes what nodes should be visited in the active document.
includeDependencies (bool, default=False) – Whether to include node dependencies or not.

Returns:

The number of nodes.

Return type:

int

Examples

Get a number of atoms in the active document:

>>> number_of_atoms = SAMSON.countNodes('node.type atom')

countNodes(nodeType: samson.SBNode.Type, selectedNodesOnly: bool = False, visitString: str = ‘*’, includeDependencies: bool = False) -> int

Counts nodes in the active document, based on nodeType and other parameters.

This function traverses the active document’s sub-tree for which a predicate based on the visitString is True (depth-first), and counts nodes whose type is nodeType. Precisely, if the predicate based on the visitString returns false, the node is not visited, and neither are its descendants. If the predicate based on the visitString returns True, the node is visited, and this visit predicate will be used to decide whether its children are visited or not. Note that the node itself must satisfy the predicate based on the visitString else nothing is visited.

When includeDependencies is True, the function also counts nodes that are not descendants of this node, but are dependencies nonetheless. For example, in a SBBond, the two atoms connected by the bond are not children of the bond, but are still dependencies of the bond. Hence, provided they satisfy the nodeType and visitString, they are counted if includeDependencies is True.

Parameters:

nodeType (samson.SBNode.Type) – A type of nodes that should be collected.
selectedNodesOnly (bool, default=False) – If set to True, then only nodes that are selected, directly or via their parents, will be traversed.
visitString (str, default='*') – A Node Specification Language expression (SAMSON API: Node Specification Language) that describes what nodes should be visited in the active document.
includeDependencies (bool, default=False) – Whether to include node dependencies or not.

Returns:

The number of nodes.

Return type:

int

Examples

Get a number of residues in the active document:

>>> number_of_residues = SAMSON.countNodes(SBNode.Residue)

samson.SAMSON.createRenderPreset() → samson.SBRenderPreset#: Creates a render preset based on the current rendering settings; returns the owning pointer

samson.SAMSON.disableHolding() → None#: Pauses holding.

See also

isHolding, enableHolding, beginHolding, hold, endHolding

samson.SAMSON.enableHolding() → None#: Resumes holding.

See also

isHolding, disableHolding, beginHolding, hold, endHolding

samson.SAMSON.endHolding() → None#: Ends holding.

See also

beginHolding, hold, isHolding, disableHolding, enableHolding

samson.SAMSON.exit() → None#: Exits SAMSON with a dialog

samson.SAMSON.exportToFile(*args, **kwargs)#

Overloaded function.

exportToFile(nodeIndexer: samson.SBNodeIndexer, fileName: str) -> None

Export a collection of nodes in the nodeIndexer to a file. The format of the file is based on its extension.

Parameters:

nodeIndexer (samson.SBNodeIndexer) – An indexer of nodes that should be exported.
fileName (str) – A path to the file.

Examples

Export all structural models from the active document into a PDB file.

>>> nodeIndexer = SAMSON.getNodes('node.type structuralModel')
>>> SAMSON.exportToFile(nodeIndexer, '/home/user/example.pdb')

See also

importFromFile

exportToFile(nodeIndexer: samson.SBNodeIndexer, fileName: str, parameters: list[str]) -> None

Export a collection of nodes in the nodeIndexer to a file with parameters specific to the exporter associated with the format of the file. The format of the file is based on its extension.

Parameters:

nodeIndexer (samson.SBNodeIndexer) – An indexer of nodes that should be exported.
fileName (str) – A path to the file.
parameters (list) – A list of parameters (str) for the exporter.

See also

importFromFile

samson.SAMSON.fetchPDB(pdbCode: str, extension: str = 'pdb') → None#

Fetch structure from RCSB PDB and import it into SAMSON.

Parameters:

pdbCode (str) – A PDB code.
extension (str, default='pdb') – A format, e.g. ‘pdb’, ‘cif’, ‘mmtf’.

Examples

Fetch the 1YRF structure and load it in SAMSON.

>>> SAMSON.fetchPDB('1YRF', 'mmtf')

See also

importFromFile, exportToFile

samson.SAMSON.getAction(actionUUID: samson.SBUUID) → samson.SBAction#

Return the action with the given actionUUID.

Parameters:: actionUUID (samson.SBUUID) – A UUID of a command (action).
Returns:: True if an action was found, else False.
Return type:: bool

See also

getActionByText, runCommand

samson.SAMSON.getActionByText(text: str) → samson.SBAction#

Return the first found action with the given text.

Parameters:: text (str) – A name of an action (command), may include a path to this action (command) in the ribbon menu.
Returns:: An action, or None if not found.
Return type:: samson.SBAction

Examples

Find and trigger an action.

>>> action = SAMSON.getActionByText('Ribbons')
>>> if action: action.trigger()
>>> else: print("Could not find the action")

See also

runCommand, getAction

samson.SAMSON.getActiveCamera() → samson.SBCamera#

Returns the active camera from the active document. Note: SAMSON always has an active camera.

Returns:: The active camera in the active document
Return type:: samson.SBCamera

Examples

Go to the front view with the active camera.

>>> SAMSON.getActiveCamera().frontView()

See also

getActiveDocument

samson.SAMSON.getActiveDocument() → samson.SBDocument#

Returns the active document. Note: SAMSON always has an active document.

Returns:: The active document
Return type:: samson.SBDocument

Examples

Clear the selection in the active document.

>>> SAMSON.getActiveDocument().clearSelection()

samson.SAMSON.getActiveDocumentFilter() → str#

Returns the node filter of the active document in the Document View.

Returns:: The current node filter in the Document View.
Return type:: str

See also

setActiveDocumentFilter

samson.SAMSON.getActiveSelectionFilterNSL() → str#

Returns the active selection filter NSL string.

Returns:: The current selection filter Node Specification Language (NSL) expression string (SAMSON API: Node Specification Language).
Return type:: str

Examples

>>> SAMSON.getActiveSelectionFilterNSL()
'n.t r'

samson.SAMSON.getActiveSelectionFilterName() → str#

Returns the active selection filter name.

Returns:: The current selection filter name.
Return type:: str

Examples

>>> SAMSON.getActiveSelectionFilterName()
'Atoms and bonds'

samson.SAMSON.getActiveStructuralModel() → samson.SBStructuralModel#

Returns the active structural model in the active document.

Returns:: The active structural model in the document, if any, else return None
Return type:: samson.SBStructuralModel

Examples

Get the active structural model in the active document.

>>> active_structural_model = SAMSON.getActiveStructuralModel()

See also

setActiveStructuralModel

samson.SAMSON.getAnimationProxyMap() → dict[str, samson.SBProxy]#: Returns a map between public names of animations and their proxies

samson.SAMSON.getAtom(x: int, y: int) → samson.SBAtom#

Returns the atom at location (x, y) in the viewport.

Parameters:

x (int) – x-coordinate in the viewport.
y (int) – y-coordinate in the viewport.

Returns:

An atom.

Return type:

samson.SBAtom

Examples

Get an atom at the given coordinates in the viewport:

>>> atom = SAMSON.getAtom(100, 200)

See also

getBond, getNode, getNodes

samson.SAMSON.getAtomRadius() → samson.SBQuantity.unitsSI#

Get the radius of atoms in the default representation of structural models.

Returns:: A radius of atoms.
Return type:: samson.SBQuantity

Examples

>>> SAMSON.getAtomRadius()
30.000000 pm

samson.SAMSON.getAtomicWeight(element: samson.SBElement.ElementType) → samson.SBQuantity.unitsSI#

Returns the atomic weight of a periodic table element.

Parameters:: element (samson.SBElement.ElementType) – A type of the periodic table element
Returns:: An atomic weight of the given periodic table element.
Return type:: samson.SBQuantity

Examples

Get an atomic weight of a periodic table element in Daltons.

>>> atomic_weight = SAMSON.getAtomicWeight(SBElement.C)
>>> print(atomic_weight.Da)
12.011 Da

samson.SAMSON.getBlock(element: samson.SBElement.ElementType) → str#

Returns the block of a periodic table element.

Parameters:: element (samson.SBElement.ElementType) – A type of the periodic table element
Returns:: A block of the given periodic table element.
Return type:: str

Examples

Get a block of a periodic table element.

>>> SAMSON.getBlock(SBElement.Fe)
'd'

samson.SAMSON.getBond(x: int, y: int) → samson.SBBond#

Returns the bond at location (x, y) in the viewport.

Parameters:

x (int) – x-coordinate in the viewport.
y (int) – y-coordinate in the viewport.

Returns:

A bond.

Return type:

samson.SBBond

Examples

Get a bond at the given coordinates in the viewport:

>>> bond = SAMSON.getBond(100, 200)

See also

getAtom, getNode, getNodes

samson.SAMSON.getBondRadius() → samson.SBQuantity.unitsSI#

Get the radius of bonds in the default representation of structural models.

Returns:: A radius of bonds.
Return type:: samson.SBQuantity

Examples

>>> SAMSON.getBondRadius()
10.000000 pm

samson.SAMSON.getCameraControllerFlag() → bool#: Returns True when the camera controller should be displayed in the viewport.

samson.SAMSON.getChoiceFromUser(dialogTitle: str, currentIndex: int, label: str, choices: list[str], toolTips: list[str]) → tuple#

Gets a choice from the user in a modal pop-up dialog.

Parameters:

dialogTitle (str) – A title of the pop-up dialog.
currentIndex (int) – The input index
label (str) – The description label in the dialog
choices (list of str) – The list of choices
toolTips (list of str) – The list of tool tips for choices

Returns:

A tuple with the status as the 1st value and the index as the 2nd value. If OK was clicked, then the 1st value of the tuple is True and the second one is the chosen index. If Cancel was clicked, then the 1st value of the tuple is False and the second one is input index.

Return type:

Tuple(bool, int)

samson.SAMSON.getColorFromUser(dialogTitle: str = 'Choose a color', color: samson.SBColor = SBColor(1.000000, 1.000000, 1.000000, 1.000000)) → tuple#

Gets a color from the user in a modal pop-up dialog.

Parameters:

dialogTitle (str, default='Choose a color') – A title of the pop-up dialog.
color (samson.SBColor, default=SBColor()) – The input color

Returns:

A tuple with the status as the 1st value and the color as the 2nd value. If OK was clicked, then the 1st value of the tuple is True and the second one is the chosen color. If Cancel was clicked, then the 1st value of the tuple is False and the second one is the input color.

Return type:

Tuple(bool, samson.SBColor)

Examples

>>> status, color = SAMSON.getColorFromUser("Choose a color")

See also

getPaletteFromUser

samson.SAMSON.getColorSchemeProxyMap() → dict[str, samson.SBProxy]#: Returns a map between public names of color schemes and their proxies

samson.SAMSON.getCovalentRadius(*args, **kwargs)#

Overloaded function.

getCovalentRadius(element: samson.SBElement.ElementType) -> samson.SBQuantity.unitsSI

Returns the covalent radius of a periodic table element.

Parameters:: element (samson.SBElement.ElementType) – A type of the periodic table element
Returns:: A covalent radius of the given periodic table element.
Return type:: samson.SBQuantity

Examples

Get a covalent radius of a periodic table element in angstroms.

>>> covalent_radius = SAMSON.getCovalentRadius(SBElement.Ar)
>>> print(covalent_radius.angstrom)
1.06 Å

getCovalentRadius(element: samson.SBElement.ElementType, bondType: int) -> samson.SBQuantity.unitsSI

Returns the covalent radius of a periodic table element for bond type bondType (1 for single bond, 2 for double bond, 3 for triple bond, for other values it returns getCovalentRadius())

Parameters:

element (samson.SBElement.ElementType) – A type of the periodic table element
bondType ({1, 2, 3}) – A bond type: 1 - single, 2 - double, 3 - triple.

Returns:

A covalent radius of the given periodic table element for the given bond type.

Return type:

samson.SBQuantity

Examples

Get a covalent radius of a double bond to Carbon in angstroms.

>>> covalent_radius = SAMSON.getCovalentRadius(SBElement.C, 2)
>>> print(covalent_radius.angstrom)
0.67 Å

samson.SAMSON.getDarkModeFlag() → bool#: Returns true when dark mode is on

samson.SAMSON.getDeepSelectionFlag() → bool#: Returns whether the user wants deep selection.

samson.SAMSON.getDoubleFromUser(dialogTitle: str, currentValue: float, minimum: float, maximum: float, singleStep: float = 1.0, prefix: str = '', suffix: str = '', decimals: int = 2) → tuple#

Gets a float number from the user in a modal pop-up dialog.

Parameters:

dialogTitle (str) – A title of the pop-up dialog.
currentValue (float) – The current value.
minimum (float) – A minimum value.
maximum (float) – A maximum value.
singleStep (float, default=1.0) – A single step value when changing values in the spin box.
prefix (str, default='') – A prefix shown in the spin box.
suffix (str, default='') – A suffix shown in the spin box.
decimals (int, default=2) – A number of decimals shown in the spin box.

Returns:

A tuple with the status as the 1st value and the result as the 2nd value. If OK was clicked, then the 1st value of the tuple is True and the second one is the chosen value. If Cancel was clicked, then the 1st value of the tuple is False and the second one is currentValue.

Return type:

Tuple(bool, float)

Examples

>>> status, value = SAMSON.getDoubleFromUser('Choose a value...', 0.5, -1.5, 9.6)

samson.SAMSON.getDoubleIntervalFromUser(dialogTitle: str, labelsText: list[str], currentValues: tuple[float, float], minValueInterval: tuple[float, float], maxValueInterval: tuple[float, float], singleStep: tuple[float, float] = (1.0, 1.0), prefix: str = '', suffix: str = '') → tuple#

Gets a float interval from the user in a modal pop-up dialog.

Parameters:

dialogTitle (str) – A title of the pop-up dialog.
labelsText (tuple of str, size=3) – A text in the main label and in labels for the left and right values of the interval.
currentValues (tuple of float, size=2) – A tuple of size 2 with the current values for the left and right values of the interval.
minValueInterval (tuple of float, size=2) – A tuple of size 2 describing the range of values for the left value of the interval.
maxValueInterval (tuple of float, size=2) – A tuple of size 2 describing the range of values for the right value of the interval.
singleStep (tuple of float, default=(1, 1)) – A tuple of single step values (when changing values in the spin box) for the left and right values of the interval.
prefix (str, default='') – A prefix shown in the spin box.
suffix (str, default='') – A suffix shown in the spin box.

Returns:

A tuple with the status as the 1st value and the result interval as the 2nd value. If OK was clicked, then the 1st value of the tuple is True and the second one is the chosen value interval as a tuple. If Cancel was clicked, then the 1st value of the tuple is False and the second one is currentValues.

Return type:

Tuple(bool, Tuple(float, float))

Examples

>>> status, value = SAMSON.getDoubleIntervalFromUser('Choose an interval...',
>>>     ('Choose min and max', 'min', 'max'), (1.5, 7.5), (0, 3), (4, 10))

samson.SAMSON.getElectronegativity(element: samson.SBElement.ElementType) → samson.SBQuantity.unitsSI#

Returns the electronegativity of a periodic table element.

Parameters:: element (samson.SBElement.ElementType) – A type of the periodic table element
Returns:: An electronegativity of the given periodic table element (dimensionless).
Return type:: samson.SBQuantity

Examples

Get an electronegativity of a periodic table element.

>>> electronegativity = SAMSON.getElectronegativity(SBElement.O)
>>> print(electronegativity)
3.440000 (dimensionless)

samson.SAMSON.getElementFromUser(dialogTitle: str = 'Select an element', currentElement: samson.SBElement.ElementType = <ElementType.Unknown: 0>) → tuple#

Gets a periodic table element from the user in a modal pop-up dialog.

Parameters:

dialogTitle (str, default='Select an element') – A title of the pop-up dialog.
currentElement (samson.SBElement.ElementType, default=SBElement.Unknown) – The current element.

Returns:

A tuple with the status as the 1st value and the result as the 2nd value. If OK was clicked, then the 1st value of the tuple is True and the second one is the user-chosen element. If Cancel was clicked, then the 1st value of the tuple is False and the second one is SBElement.Unknown.

Return type:

Tuple(bool, str)

Examples

>>> status, value = SAMSON.getElementFromUser()

See also

getElementsFromUser

samson.SAMSON.getElementName(element: samson.SBElement.ElementType) → str#

Returns the name of the periodic table element corresponding to the given type.

Parameters:: element (samson.SBElement.ElementType) – A type of the periodic table element
Returns:: A name of the given periodic table element.
Return type:: str

Examples

Get a name of a periodic table element.

>>> SAMSON.getElementName(SBElement.N)
'Nitrogen'

samson.SAMSON.getElementSymbol(element: samson.SBElement.ElementType) → str#

Returns the symbol of the periodic table element corresponding to the given type.

Parameters:: element (samson.SBElement.ElementType) – A type of the periodic table element
Returns:: A symbol of the given periodic table element.
Return type:: str

Examples

Get a symbol of a periodic table element.

>>> SAMSON.getElementSymbol(SBElement.O)
'O'

samson.SAMSON.getElementTypeByName(elementName: str) → samson.SBElement.ElementType#

Returns the periodic table element type corresponding to the given name.

Parameters:: elementName (str) – A name of a periodic table element.
Returns:: A type of the periodic table element.
Return type:: samson.SBElement.ElementType

Examples

Get a type of a periodic table element.

>>> SAMSON.getElementTypeByName('Nitrogen')
<ElementType.Nitrogen: 7>

samson.SAMSON.getElementTypeBySymbol(elementSymbol: str) → samson.SBElement.ElementType#

Returns the periodic table element type corresponding to the given symbol.

Parameters:: elementSymbol (str) – A symbol of a periodic table element.
Returns:: A type of the periodic table element.
Return type:: samson.SBElement.ElementType

Examples

Get a type of a periodic table element.

>>> SAMSON.getElementTypeBySymbol('Ca')
<ElementType.Calcium: 20>

samson.SAMSON.getElementsFromUser(dialogTitle: str = 'Select elements', currentElement: list[samson.SBElement.ElementType] = []) → tuple#

Gets a list of periodic table elements from the user in a modal pop-up dialog.

Parameters:

dialogTitle (str, default='Select elements') – A title of the pop-up dialog.
currentElements (list of samson.SBElement.ElementType, default=empty list) – A list of elements.

Returns:

A tuple with the status as the 1st value and the result as the 2nd value. If OK was clicked, then the 1st value of the tuple is True and the second one is the list of user-chosen elements. If Cancel was clicked, then the 1st value of the tuple is False and the second one is an empty list.

Return type:

Tuple(bool, str)

Examples

>>> status, value = SAMSON.getElementsFromUser()

See also

getElementFromUser

samson.SAMSON.getFileNameFromUser(dialogTitle: str = 'Choose a file', currentFileName: str = '', dir: str = '', filter: str = '') → tuple#

Gets a filename from the user in a modal pop-up dialog.

Parameters:

dialogTitle (str, default='Choose a file') – A title of the pop-up dialog.
currentFileName (str, default='') – The current file name.
dir (str, default='') – The directory.
filter (str, default='') – The file extension filter

Returns:

A tuple with the status as the 1st value and the result as the 2nd value. If OK was clicked, then the 1st value of the tuple is True and the second one is the chosen file name. If Cancel was clicked, then the 1st value of the tuple is False and the second one is an empty string.

Return type:

Tuple(bool, str)

Examples

>>> status, value = SAMSON.getFileNameFromUser()

samson.SAMSON.getFileNamesFromUser(dialogTitle: str = 'Choose files', dir: str = '', filter: str = '') → tuple#

Gets a list of filenames from the user in a modal pop-up dialog.

Parameters:

dialogTitle (str, default='Choose files') – A title of the pop-up dialog.
dir (str, default='') – The directory.
filter (str, default='') – The file extension filter

Returns:

A tuple with the status as the 1st value and the result as the 2nd value. If OK was clicked, then the 1st value of the tuple is True and the second one is the list of file names. If Cancel was clicked, then the 1st value of the tuple is False and the second one is an empty list.

Return type:

Tuple(bool, str)

Examples

>>> status, list_of_filenames = SAMSON.getFileNamesFromUser()

samson.SAMSON.getGridFlag() → bool#: Returns True when the grid should be displayed in the viewport.

samson.SAMSON.getGroup(element: samson.SBElement.ElementType) → int#

Returns the group of a periodic table element.

Parameters:: element (samson.SBElement.ElementType) – A type of the periodic table element
Returns:: A group of the given periodic table element.
Return type:: int

Examples

Get a group of a periodic table element.

>>> SAMSON.getGroup(SBElement.S)
16

samson.SAMSON.getIntegerFromUser(dialogTitle: str, currentValue: int, minimum: int, maximum: int, singleStep: int = 1, prefix: str = '', suffix: str = '') → tuple#

Gets an int number from the user in a modal pop-up dialog.

Parameters:

dialogTitle (str) – A title of the pop-up dialog.
currentValue (int) – The current value.
minimum (int) – A minimum value.
maximum (int) – A maximum value.
singleStep (int, default=1) – A single step value when changing values in the spin box.
prefix (str, default='') – A prefix shown in the spin box.
suffix (str, default='') – A suffix shown in the spin box.

Returns:

Return type:

Tuple(bool, int)

Examples

>>> status, value = SAMSON.getIntegerFromUser('Choose a value...', 5, 0, 10)

samson.SAMSON.getIntegerIntervalFromUser(dialogTitle: str, labelsText: list[str], currentValues: tuple[int, int], minValueInterval: tuple[int, int], maxValueInterval: tuple[int, int], singleStep: tuple[int, int] = (1, 1), prefix: str = '', suffix: str = '') → tuple#

Gets an int interval from the user in a modal pop-up dialog

Parameters:

dialogTitle (str) – A title of the pop-up dialog.
labelsText (tuple of str, size=3) – A text in the main label and in labels for the left and right values of the interval.
currentValues (tuple of int, size=2) – A tuple of size 2 with the current values for left and right values of the interval.
minValueInterval (tuple of int, size=2) – A tuple of size 2 describing the range of values for the left value of the interval.
maxValueInterval (tuple of int, size=2) – A tuple of size 2 describing the range of values for the right value of the interval.
singleStep (tuple of int, default=(1, 1)) – A tuple of single step values (when changing values in the spin box) for the left and right values of the interval.
prefix (str, default='') – A prefix shown in the spin box.
suffix (str, default='') – A suffix shown in the spin box.

Returns:

A tuple with the status as the 1st value and the result as the 2nd value. If OK was clicked, then the 1st value of the tuple is True and the second one is the chosen value interval as a tuple. If Cancel was clicked, then the 1st value of the tuple is False and the second one is currentValues.

Return type:

Tuple(bool, Tuple(int, int))

Examples

>>> status, value = SAMSON.getIntegerIntervalFromUser('Choose an interval...',
>>>     ('Choose min and max', 'min', 'max'), (0, 5), (0, 3), (4, 10))

samson.SAMSON.getItemFromUser(*args, **kwargs)#

Overloaded function.

getItemFromUser(dialogTitle: str, label: str, items: list[str], currentIndex: int = 0) -> tuple

Gets an item from the user in a modal pop-up dialog.

Parameters:

dialogTitle (str) – A title of the pop-up dialog.
label (str) – A label that will be shown in the dialog.
items (list of str) – A list of items.
currentIndex (int, default=0) – An index of the currently chosen item.

Returns:

A tuple with the status as the 1st value and the result as the 2nd value. If OK was clicked, then the 1st value of the tuple is True and the second one is the text of the chosen item. If Cancel was clicked, then the 1st value of the tuple is False and the second one is an empty list.

Return type:

Tuple(bool, str)

Examples

>>> status, text = SAMSON.getItemFromUser('Choose item', 'Choose an item from the list below',
>>>     ['foo', 'bar'], 1)

getItemFromUser(dialogTitle: str, currentIndex: int, label: str, items: list[str]) -> tuple

Gets an item from the user in a modal pop-up dialog.

Parameters:

dialogTitle (str) – A title of the pop-up dialog.
currentIndex (int) – An index of the currently chosen item.
label (str) – A label that will be shown in the dialog.
items (list of str) – A list of items.

Returns:

A tuple with the status as the 1st value and the result as the 2nd value. If OK was clicked, then the 1st value of the tuple is True and the second one is the index of the chosen item. If Cancel was clicked, then the 1st value of the tuple is False and the second one is an empty list.

Return type:

Tuple(bool, str)

Examples

>>> status, idx = SAMSON.getItemFromUser('Choose item', 1, 'Choose an item from the list below',
>>>     ['foo', 'bar'])

samson.SAMSON.getLikeFromUser(developerUUID: samson.SBUUID, extensionUUID: samson.SBUUID) → None#

Asks the user to reply to a question.

Parameters:

developerUUID (samson.SBUUID) – The UUID of the registered developer.
extensionUUID (samson.SBUUID) – The UUID of the SAMSON Extension.

samson.SAMSON.getMaximum3DTextureSize() → int#: Returns the maximum 3D texture size.

samson.SAMSON.getMaximumRectangleTextureSize() → int#: Returns the maximum rectangle texture size.

samson.SAMSON.getMaximumTextureSize() → int#: Returns the maximum texture size.

samson.SAMSON.getMousePositionInViewport() → tuple[int, int]#

Returns the current mouse position in viewport coordinates.

Returns:: The current mouse position in the viewport coordinates.
Return type:: Tuple(int, int)

samson.SAMSON.getMultiSampleFactor() → int#: Returns the multisampling factor.

samson.SAMSON.getMultipleBondDisplayFlag() → bool#: Returns True when bonds are displayed with a variable number of cylinders to represent their order

samson.SAMSON.getNextNodeName(type: samson.SBNode.Type, prefix: str = '', suffix: str = '', parentNode: samson.SBNode = None) → str#

Returns a next name starting with prefix and ending with suffix for nodes of type type in parent node parentNode or in the active document if parentNode is None.

Parameters:

type (samson.SBNode.Type) – A node type
prefix (str, default='') – The name prefix
suffix (str, default='') – The name suffix
parentNode (samson.SBNode, default=None) – The parent node. If None then the whole document is considered.

Returns:

The next node name

Return type:

str

samson.SAMSON.getNode(x: int, y: int, selectionFilter: str = '*') → samson.SBNode#

Returns the node at location (x, y) in the viewport based on the selection filter selectionString.

Parameters:

x (int) – x-coordinate in the viewport.
y (int) – y-coordinate in the viewport.
selectionString (str, default='*') – A Node Specification Language expression (SAMSON API: Node Specification Language).

Returns:

A node.

Return type:

samson.SBNode

Examples

Get an atom at the given coordinates in the viewport:

>>> node = SAMSON.getNode(100, 200, "node.type atom")

See also

getAtom, getBond, getNodes

samson.SAMSON.getNodes(*args, **kwargs)#

Overloaded function.

getNodes(x: int, y: int, width: int, height: int, selectionFilter: str = ‘*’, deepSelectionFlag: bool = False) -> samson.SBNodeIndexer

Returns a node indexer with nodes found inside the viewport rectangle (x, y, width, height) based on the selection filter selectionString.

Parameters:

x (int) – x-coordinate in the viewport.
y (int) – y-coordinate in the viewport.
width (int) – The width of the rectangle.
height (int) – The height of the rectangle.
selectionString (str, default='*') – A Node Specification Language expression (SAMSON API: Node Specification Language).
deepSelectionFlag (bool, default=False) – Whether the deep selection should be done or not. If set to True, then all the nodes behind the given rectangle even that are not visible now due to e.g. depth-of-field or fog will be chosen.

Returns:

A node indexer.

Return type:

samson.SBNodeIndexer

Examples

Get a node indexer with atoms in the given rectangle in the viewport:

>>> nodeIndexer = SAMSON.getNodes(100, 200, 50, 50, "node.type atom")

See also

getAtom, getBond, getNode

getNodes(selectionString: str = ‘*’, visitString: str = ‘*’, includeDependencies: bool = False) -> samson.SBNodeIndexer

Returns a node indexer with nodes from the active document based on the provided selection filter selectionString and other parameters.

This function traverses the active document’s sub-tree for which a predicate based on the visitString is True (depth-first), and stores in nodeIndexer the nodes for which the selectionString is True. Precisely, if the predicate based on the visitString returns false, the node is not visited, and neither are its descendants. If the predicate based on the visitString returns True, the node is visited, and this visit predicate will be used to decide whether its children are visited or not. Note that the node itself must satisfy the predicate based on the visitString else nothing is visited.

When includeDependencies is True, the function also adds to nodeIndexer nodes that are not descendants of this node, but are dependencies nonetheless. For example, in a SBBond, the two atoms connected by the bond are not children of the bond, but are still dependencies of the bond. Hence, provided they satisfy the selectionString and visitString, they are added to the nodeIndexer if includeDependencies is True.

Parameters:

selectionString (str, default='*') – A Node Specification Language expression (SAMSON API: Node Specification Language) that describes what nodes should be selected from the active document.
visitString (str, default='*') – A Node Specification Language expression (SAMSON API: Node Specification Language) that describes what nodes should be visited in the active document.
includeDependencies (bool, default=False) – Whether to include node dependencies or not.

Returns:

A node indexer.

Return type:

samson.SBNodeIndexer

Examples

Get a node indexer with all atoms in the active document:

>>> nodeIndexer = SAMSON.getNodes('node.type atom')

getNodes(nodeIndexer: samson.SBNodeIndexer, selectionString: str = ‘*’, visitString: str = ‘*’, includeDependencies: bool = False) -> None

Collects into the nodeIndexer nodes from the active document based on the provided selection filter selectionString and other parameters.

Parameters:

nodeIndexer (samson.SBNodeIndexer) – An existing node indexer in which nodes should be added. Note that this node indexer is not cleared in the function.
selectionString (str, default='*') – A Node Specification Language expression (SAMSON API: Node Specification Language) that describes what nodes should be selected from the active document.
visitString (str, default='*') – A Node Specification Language expression (SAMSON API: Node Specification Language) that describes what nodes should be visited in the active document.
includeDependencies (bool, default=False) – Whether to include node dependencies or not.

Notes

The nodeIndexer is not cleared when entering this function.

Examples

Collect in an existing nodeIndexer all residues from the active document:

>>> nodeIndexer = SBNodeIndexer()
>>> SAMSON.getNodes(nodeIndexer, 'node.type residue')

getNodes(nodeType: samson.SBNode.Type, selectedNodesOnly: bool = False, visitString: str = ‘*’, includeDependencies: bool = False) -> samson.SBNodeIndexer

Returns a node indexer with nodes from the active document based on the provided nodeType, a selection status, a visit predicate, with or without dependencies.

This function traverses the active document’s sub-tree for which a predicate based on the visitString is True (depth-first), and stores in nodeIndexer the nodes whose type is nodeType. Precisely, if the predicate based on the visitString returns false, the node is not visited, and neither are its descendants. If the predicate based on the visitString returns True, the node is visited, and this visit predicate will be used to decide whether its children are visited or not. Note that the node itself must satisfy the predicate based on the visitString else nothing is visited.

When includeDependencies is True, the function also adds to nodeIndexer nodes that are not descendants of this node, but are dependencies nonetheless. For example, in a SBBond, the two atoms connected by the bond are not children of the bond, but are still dependencies of the bond. Hence, provided they satisfy the nodeType and visitString, they are added to the nodeIndexer if includeDependencies is True.

Parameters:

nodeType (samson.SBNode.Type) – A type of nodes that should be collected.
selectedNodesOnly (bool, default=False) – If set to True, then only nodes that are selected, directly or via their parents, will be traversed.
visitString (str, default='*') – A Node Specification Language expression (SAMSON API: Node Specification Language) that describes what nodes should be visited in the active document.
includeDependencies (bool, default=False) – Whether to include node dependencies or not.

Returns:

A node indexer.

Return type:

samson.SBNodeIndexer

Examples

Get a node indexer with all atoms in the active document:

>>> nodeIndexer = SAMSON.getNodes(SBNode.Atom)

getNodes(nodeIndexer: samson.SBNodeIndexer, nodeType: samson.SBNode.Type, selectedNodesOnly: bool = False, visitString: str = ‘*’, includeDependencies: bool = False) -> None

Collects into the provided nodeIndexer nodes from the active document based on the provided nodeType, a selection status, a visit predicate, with or without dependencies.

When includeDependencies is True, the function also adds to nodeIndexer nodes that are not descendants of this node, but are dependencies nonetheless. For example, in a SBBond, the two atoms connected by the bond are not children of the bond, but are still dependencies of the bond. Hence, provided they satisfy the nodeType and visitString, they are added to the nodeIndexer if includeDependencies is True.

Parameters:

nodeIndexer (samson.SBNodeIndexer) – An existing node indexer in which nodes should be added. Note that this node indexer is not cleared in the function.
nodeType (samson.SBNode.Type) – A type of nodes that should be collected.
selectedNodesOnly (bool, default=False) – If set to True, then only nodes that are selected, directly or via their parents, will be traversed.
visitString (str, default='*') – A Node Specification Language expression (SAMSON API: Node Specification Language) that describes what nodes should be visited in the active document.
includeDependencies (bool, default=False) – Whether to include node dependencies or not.

Notes

The nodeIndexer is not cleared when entering this function.

Examples

Get a node indexer with all bonds in the active document:

>>> nodeIndexer = SBNodeIndexer()
>>> SAMSON.getNodes(nodeIndexer, SBNode.Bond)

samson.SAMSON.getNumberOfElements() → int#: Returns the number of defined periodic table elements, including the Unknown element.

samson.SAMSON.getPaletteFromUser(dialogTitle: str = 'Choose a color palette', defaultColorPalette: samson.SBPalette = None) → tuple#

Gets a color palette from the user in a modal pop-up dialog.

Parameters:

dialogTitle (str, default='Choose a color palette') – A title of the pop-up dialog.
defaultColorPalette (samson.SBPalette) – A default color palette.

Returns:

A tuple with the status as the 1st value and the color palette as the 2nd value. If OK was clicked, then the 1st value of the tuple is True and the second one is the chosen color palette. If Cancel was clicked, then the 1st value of the tuple is False and the second one is the defaultColorPalette.

Return type:

Tuple(bool, samson.SBPalette)

Examples

>>> status, palette = SAMSON.getPaletteFromUser('Choose a color palette',
>>>     samson.SBPaletteDefaultPalette.qualitativeHCLPastel)

See also

getColorFromUser

samson.SAMSON.getPathFromUser(dialogTitle: str = 'Choose a path', currentPath: str = '') → tuple#

Gets a path from the user in a modal pop-up dialog.

Parameters:

dialogTitle (str, default='Choose a path') – A title of the pop-up dialog.
currentPath (str, default='') – The current path.

Returns:

A tuple with the status as the 1st value and the result as the 2nd value. If OK was clicked, then the 1st value of the tuple is True and the second one is the chosen path. If Cancel was clicked, then the 1st value of the tuple is False and the second one is an empty string.

Return type:

Tuple(bool, str)

Examples

>>> status, value = SAMSON.getPathFromUser()

samson.SAMSON.getPeriod(element: samson.SBElement.ElementType) → str#

Returns the period of a periodic table element.

Parameters:: element (samson.SBElement.ElementType) – A type of the periodic table element
Returns:: A period of the given periodic table element.
Return type:: str

Examples

Get a period of a periodic table element.

>>> SAMSON.getPeriod(SBElement.C)
'2'

samson.SAMSON.getPromptFromUser(dialogTitle: str, placeholderText: str = '') → tuple#

Gets a prompt string from the user in a modal pop-up dialog.

Parameters:

dialogTitle (str) – A title of the pop-up dialog.
placeholderText (str) – The placeholder text

Returns:

A tuple with the status as the 1st value and the string as the 2nd value. If OK was clicked, then the 1st value of the tuple is True and the second one is the user-provided string. If Cancel was clicked, then the 1st value of the tuple is False and the second one is an empty string.

Return type:

Tuple(bool, str)

samson.SAMSON.getProxy(className: str, extensionUUID: samson.SBUUID = SBUUID('')) → samson.SBProxy#

Returns the proxy of a class.

Parameters:

className (str) – A class name
extensionUUID (samson.SBUUID) – UUID of the extension that ships this class

Returns:

A found proxy. None if nothing found.

Return type:

samson.SBProxy

Examples

Get the proxy for the Ribbon visual model

>>> proxy = SAMSON.getProxy(className = "SESecondaryStructureVisualModel", extensionUUID = SBUUID("06485695-DEE2-1383-A575-E5AABA05DCCD"))
>>> if proxy: print("Found proxy")
Found proxy

samson.SAMSON.getProxyIndexer(classType: samson.SBClass.Type) → list[samson.SBProxy]#

Returns all proxies corresponding to the given class type classType.

Parameters:: classType (samson.SBClass.Type) – A class type
Return type:: list of proxies

Examples

Get a list of all visual model proxies

>>> visual_model_proxies = SAMSON.getProxyIndexer(SBClass.VisualModel)
>>> if len(visual_model_proxies): print("Found visual model proxies")
Found visual model proxies

samson.SAMSON.getPublicName(includeVersion: bool = False, includeHashInVersion: bool = False) → str#: Returns the “public name” of SAMSON.

samson.SAMSON.getPublicVersionNumber() → str#: Returns the “public version number” of SAMSON.

samson.SAMSON.getReplyFromUser(developerUUID: samson.SBUUID, questionUUID: samson.SBUUID) → None#

Asks the user to reply to a question.

Parameters:

developerUUID (samson.SBUUID) – The UUID of the registered developer.
questionUUID (samson.SBUUID) – The UUID of the registered question.

samson.SAMSON.getSAMSONElementsPath() → str#: Returns the path where SAMSON Extensions (Elements) are installed

samson.SAMSON.getSAMSONPath() → str#: Returns the path where SAMSON is installed

samson.SAMSON.getSaveFileNameFromUser(dialogTitle: str = 'Choose a filename', currentFileName: str = '', dir: str = '', filter: str = '') → tuple#

Gets a filename from the user in a modal pop-up dialog with a Save button.

Parameters:

dialogTitle (str, default='Choose a filename') – A title of the pop-up dialog.
currentFileName (str, default='') – The current file name.
dir (str, default='') – The directory.
filter (str, default='') – The file extension filter

Returns:

Return type:

Tuple(bool, str)

Examples

>>> status, value = SAMSON.getSaveFileNameFromUser()

samson.SAMSON.getScaleFlag() → bool#: Returns True when the scale should be displayed in the viewport.

samson.SAMSON.getScratchPath() → str#: Returns the path to scratch data

samson.SAMSON.getSelectorProxyMap() → dict[str, samson.SBProxy]#: Returns a map between public names of selectors and their proxies

samson.SAMSON.getSimulationFlag() → bool#

Returns True when interactive simulation is on.

Returns:: True when interactive simulation is on, else False.
Return type:: bool

samson.SAMSON.getStringFromUser(dialogTitle: str = 'Set a string', currentString: str = '') → tuple#

Gets a string from the user in a modal pop-up dialog.

Parameters:

dialogTitle (str, default='Set a string') – A title of the pop-up dialog.
currentString (str, default='') – The current string.

Returns:

A tuple with the status as the 1st value and the result as the 2nd value. If OK was clicked, then the 1st value of the tuple is True and the second one is the user-provided string. If Cancel was clicked, then the 1st value of the tuple is False and the second one is an empty string.

Return type:

Tuple(bool, str)

Examples

>>> status, value = SAMSON.getStringFromUser('Set a string', 'Example: ...')

samson.SAMSON.getTime() → int#: Returns SAMSON’s internal time

samson.SAMSON.getUserDataPath() → str#: Returns the path where user data is installed

samson.SAMSON.getUserPlan() → samson.SBUserPlan#: Returns the user plan

samson.SAMSON.getUserPlanString() → str#: Returns a string containing the user plan

samson.SAMSON.getVanDerWaalsAtomRadiusFlag() → bool#: Returns True when atoms are displayed with a radius proportional to their van der Waals radius

samson.SAMSON.getVanDerWaalsAtomRadiusRatio() → float#: Returns the constant by which the atoms van der Waals radius is multiplied to represent atoms in the viewport (when a constant radius is not used)

samson.SAMSON.getVanDerWaalsRadius(element: samson.SBElement.ElementType) → samson.SBQuantity.unitsSI#

Returns the van der Waals radius of a periodic table element.

Parameters:: element (samson.SBElement.ElementType) – A type of the periodic table element
Returns:: A van der Waals radius of the given periodic table element.
Return type:: samson.SBQuantity

Examples

Get a van der Waals radius of a periodic table element in nanometers.

>>> vdw_radius = SAMSON.getVanDerWaalsRadius(SBElement.S)
>>> print(vdw_radius.nm)
0.18

samson.SAMSON.getVersionNumber() → samson.SBVersionNumber#: Returns the version number of SAMSON.

samson.SAMSON.getViewportHeight() → int#

Returns the viewport height.

Returns:: The viewport height.
Return type:: int

Examples

Get the viewport width:

>>> SAMSON.getViewportHeight()
640

samson.SAMSON.getViewportPixelRatio() → float#: Returns the viewport pixel ratio

samson.SAMSON.getViewportPositionFromWorldPosition(position: samson.SBPhysicalVector3) → samson.SBPhysicalVector3#: Returns the projection in the viewport of the given world position.

samson.SAMSON.getViewportWidth() → int#

Returns the viewport width.

Returns:: The viewport width.
Return type:: int

Examples

Get the viewport width:

>>> SAMSON.getViewportWidth()
1024

samson.SAMSON.getVisualModelProxyMap() → dict[str, samson.SBProxy]#: Returns a map between public names of visual models and their proxies

samson.SAMSON.hasNode(*args, **kwargs)#

Overloaded function.

hasNode(selectionString: str = ‘*’, visitString: str = ‘*’, includeDependencies: bool = False) -> bool

Checks for nodes in the active document, based on the provided selection filter selectionString and other parameters.

This function traverses the active document’s sub-tree for which a predicate based on the visitString is True (depth-first), and checks for the nodes for which the selectionString is True. Precisely, if the predicate based on the visitString returns false, the node is not visited, and neither are its descendants. If the predicate based on the visitString returns True, the node is visited, and this visit predicate will be used to decide whether its children are visited or not. Note that the node itself must satisfy the predicate based on the visitString else nothing is visited.

When includeDependencies is True, the function also checks for nodes that are not descendants of this node, but are dependencies nonetheless. For example, in a SBBond, the two atoms connected by the bond are not children of the bond, but are still dependencies of the bond. Hence, provided they satisfy the selectionString and visitString, they are checked for if includeDependencies is True.

Parameters:

selectionString (str, default='*') – A Node Specification Language expression (SAMSON API: Node Specification Language) that describes what nodes should be checked in the active document.
visitString (str, default='*') – A Node Specification Language expression (SAMSON API: Node Specification Language) that describes what nodes should be visited in the active document.
includeDependencies (bool, default=False) – Whether to include node dependencies or not.

Returns:

The number of nodes.

Return type:

int

Examples

Check if there are any atoms in the active document:

>>> res = SAMSON.hasNode('node.type atom')

hasNode(nodeType: samson.SBNode.Type, selectedNodesOnly: bool = False, visitString: str = ‘*’, includeDependencies: bool = False) -> bool

Checks for nodes in the active document, based on nodeType and other parameters.

This function traverses the active document’s sub-tree for which a predicate based on the visitString is True (depth-first), and checks for nodes whose type is nodeType. Precisely, if the predicate based on the visitString returns false, the node is not visited, and neither are its descendants. If the predicate based on the visitString returns True, the node is visited, and this visit predicate will be used to decide whether its children are visited or not. Note that the node itself must satisfy the predicate based on the visitString else nothing is visited.

When includeDependencies is True, the function also checks for nodes that are not descendants of this node, but are dependencies nonetheless. For example, in a SBBond, the two atoms connected by the bond are not children of the bond, but are still dependencies of the bond. Hence, provided they satisfy the nodeType and visitString, they are checked for if includeDependencies is True.

Parameters:

nodeType (samson.SBNode.Type) – A type of nodes that should be checked for.
selectedNodesOnly (bool, default=False) – If set to True, then only nodes that are selected, directly or via their parents, will be traversed.
visitString (str, default='*') – A Node Specification Language expression (SAMSON API: Node Specification Language) that describes what nodes should be visited in the active document.
includeDependencies (bool, default=False) – Whether to include node dependencies or not.

Returns:

The number of nodes.

Return type:

int

Examples

Check if there are any residues in the active document:

>>> res = SAMSON.hasNode(SBNode.Residue)

samson.SAMSON.hideProgressBar() → None#: Hides the progress bar.

See also

setProgressBarValue, showProgressBar, isProgressBarStopped

samson.SAMSON.hold(node: samson.SBNode) → None#

Holds a node and its descendants to make their creation undoable.

Parameters:: node (samson.SBNode) – A node.

Examples

Create a folder and add it to the active document. Make this operation undoable.

>>> SAMSON.beginHolding('Add folder')
>>> new_folder = SBFolder('New folder')
>>> SAMSON.hold(new_folder)
>>> new_folder.create()
>>> SAMSON.getActiveDocument().addChild(new_folder)
>>> SAMSON.endHolding()

samson.SAMSON.importFromFile(*args, **kwargs)#

Overloaded function.

importFromFile(fileName: str, preferredFolder: samson.SBFolder = None) -> None

Import a file from the disk.

Parameters:

fileName (str) – A path to the file
preferredFolder (samson.SBFolder, default=None) – A folder into which the system from the file should be imported.

Examples

Import a file in SAMSON.

>>> SAMSON.importFromFile('/home/user/example.pdb')

importFromFile(fileNameList: list[str], preferredFolder: samson.SBFolder = None) -> None

Import a list of files from the disk.

Parameters:

fileNameList (list of str) – A list of paths to the files.
preferredFolder (samson.SBFolder, default=None) – A folder into which systems from the files should be imported.

Examples

Import a file in SAMSON.

>>> SAMSON.importFromFile(['/home/user/example1.pdb', '/home/user/example2.pdb'])

importFromFile(fileName: str, parameters: list[str], preferredFolder: samson.SBFolder = None) -> None

Import a file from the disk with parameters specific to each importer.

Parameters:

fileName (str) – A path to the file.
parameters (list) – A list of parameters (str) for the importer.
preferredFolder (samson.SBFolder, default=None) – A folder into which the system from the file should be imported.

See also

fetchPDB, exportToFile

importFromFile(fileNameList: list[str], parameters: list[str], preferredFolder: samson.SBFolder = None) -> None

Import a list of files from the disk with parameters specific to each importer.

Parameters:

fileNameList (list of str) – A list of paths to the files.
parameters (list) – A list of parameters (str) for the importer.
preferredFolder (samson.SBFolder, default=None) – A folder into which systems from the files should be imported.

samson.SAMSON.informUser(*args, **kwargs)#

Overloaded function.

informUser(dialogTitle: str, dialogText: str) -> None

Informs the user with a message in a modal pop-up dialog.

Parameters:

dialogTitle (str) – A title of the pop-up dialog.
dialogText (str) – A text in the pop-up dialog.

Examples

>>> SAMSON.informUser('Information', 'The text of the message.')

See also

askUser

informUser(dialogTitle: str, labelText: str, text: str, monospaceFont: bool) -> None

Informs the user with a message in a modal pop-up dialog.

Parameters:

dialogTitle (str) – A title of the pop-up dialog.
labelText (str) – A text of the message label.
text (str) – A text in the plain text edit.
monospaceFont (bool) – Whether the text should be shown using a monospace font or not.

Examples

>>> SAMSON.informUser('Warning', 'Caught a warning during the execution:', 'The text of the warning.', True)

See also

askUser

samson.SAMSON.isAppInitialized(appUUID: samson.SBUUID, extensionUUID: samson.SBUUID = SBUUID('')) → bool#

Returns true or false if an app corresponding to a specific p appUUID and p elementUUID is initialized already.

Parameters:

appUUID (samson.SBUUID) – The app’s UUID
extensionUUID (samson.SBUUID) – The UUID of the extension with the app

Returns:

Whether the app is initialized or not

Return type:

bool

samson.SAMSON.isGUIThread() → bool#: Returns True if called from the main thread (GUI thread), else returns False.

samson.SAMSON.isHolding() → bool#: Returns True when SAMSON is holding.

See also

disableHolding, enableHolding, beginHolding, hold, endHolding

samson.SAMSON.isProgressBarStopped() → bool#

Returns True when the progress bar is stopped.

Return type:: True when the progress bar is stopped, else False.

samson.SAMSON.isRedoing() → bool#

Returns True while redoing.

Returns:: True while redoing, else False.
Return type:: bool

See also

isUndoing, undo, redo

samson.SAMSON.isUndoing() → bool#

Returns True while undoing.

Returns:: True while undoing, else False.
Return type:: bool

See also

isRedoing, undo, redo

samson.SAMSON.makeAnimation(*args, **kwargs)#

Overloaded function.

makeAnimation(name: str, nodeIndexer: samson.SBNodeIndexer, currentFrame: float, animationClassName: str, animationExtensionUUID: samson.SBUUID) -> samson.SBAnimation

Make an animation.

Parameters:

name (str) – A name for the animation node
nodeIndexer (samson.SBNodeIndexer) – An indexer of nodes to which the animation should be applied
currentFrame (float) – A frame at which the animation should start
animationClassName (str) – A class name of the animation
animationExtensionUUID (samson.SBUUID) – UUID of the extension with this animation

Returns:

An animation node or None if could not create one

Return type:

samson.SBAnimation

makeAnimation(name: str, nodeIndexer: samson.SBNodeIndexer, currentFrame: float, animationName: str) -> samson.SBAnimation

Make an animation.

Parameters:

name (str) – A name for the animation node
nodeIndexer (samson.SBNodeIndexer) – An indexer of nodes to which the animation should be applied
currentFrame (float) – A frame at which the animation should start
animationName (str) – A public name of the animation

Returns:

An animation node or None if could not create one

Return type:

samson.SBAnimation

samson.SAMSON.makeInteractionModel(dynamicalModel: samson.SBParticleSystem, interactionModelClassName: str, interactionModelExtensionUUID: samson.SBUUID = SBUUID('')) → samson.SBInteractionModelParticleSystem#

Make an interaction model.

Parameters:

dynamicalModel (samson.SBDynamicalModel) – A dynamical model
interactionModelClassName (str) – A class name of the interaction model
interactionModelExtensionUUID (samson.SBUUID) – UUID of the extension with this interaction model

Returns:

A interaction model or None if could not create one

Return type:

samson.SBInteractionModel

samson.SAMSON.makeNeighborSearch(dynamicalModel: samson.SBParticleSystem, cutoffDistance: samson.SBQuantity.unitsSI, neighborSearchClassName: str, neighborSearchExtensionUUID: samson.SBUUID = SBUUID('')) → samson.SBNeighborSearchParticleSystem#

Make a neighbor search algorithm.

Parameters:

dynamicalModel (samson.SBDynamicalModel) – A dynamical model
cutoffDistance (samson.SBQuantity) – A cutoff radius
neighborSearchClassName (str) – A class name of the neighbor search method
neighborSearchExtensionUUID (samson.SBUUID) – UUID of the extension with this neighbor search method

Returns:

A neighbor search or None if could not create one

Return type:

samson.SBNeighborSearch

samson.SAMSON.makePropertyModel(nodeIndexer: samson.SBNodeIndexer, propertyModelClassName: str, propertyModelExtensionUUID: samson.SBUUID = SBUUID('')) → samson.SBPropertyModel#: Make a property model

samson.SAMSON.makeSelector(*args, **kwargs)#

Overloaded function.

makeSelector(selectorClassName: str, selectorExtensionUUID: samson.SBUUID) -> samson.SBNodeSelector

Make a selector.

Parameters:

selectorClassName (str) – A class name of the selector
selectorExtensionUUID (samson.SBUUID) – UUID of the extension with this selector

Returns:

A selector or None if could not create one

Return type:

samson.SBNodeSelector

makeSelector(selectorName: str) -> samson.SBNodeSelector

Make a selector.

Parameters:: selectorName (str) – A name of the selector
Returns:: A selector or None if could not create one
Return type:: samson.SBNodeSelector

samson.SAMSON.makeSimulator(nodeIndexer: samson.SBNodeIndexer, interactionModelClassName: str, interactionModelExtensionUUID: samson.SBUUID, stateUpdaterClassName: str, stateUpdaterExtensionUUID: samson.SBUUID = SBUUID('')) → samson.SBSimulatorParticleSystem#

Make a simulator.

Parameters:

nodeIndexer (samson.SBNodeIndexer) – An indexer of nodes to which the interaction model should be applied
interactionModelClassName (str) – A class name of the interaction model
interactionModelExtensionUUID (samson.SBUUID) – UUID of the extension with this interaction model
stateUpdaterClassName (str) – A class name of the state updater
stateUpdaterExtensionUUID (samson.SBUUID) – UUID of the extension with this state updater

Returns:

A simulator or None if could not create one

Return type:

samson.SBSimulator

samson.SAMSON.makeStateUpdater(dynamicalModel: samson.SBParticleSystem, interactionModel: samson.SBInteractionModelParticleSystem, stateUpdaterClassName: str, stateUpdaterExtensionUUID: samson.SBUUID = SBUUID('')) → samson.SBStateUpdaterParticleSystem#

Make a state updater.

Parameters:

dynamicalModel (samson.SBDynamicalModel) – A dynamical model
interactionModel (samson.SBInteractionModel) – An interaction model
stateUpdaterClassName (str) – A class name of the state updater
stateUpdaterExtensionUUID (samson.SBUUID) – UUID of the extension with this state updater

Returns:

A state updater or None if could not create one

Return type:

samson.SBStateUpdater

samson.SAMSON.makeVisualModel(*args, **kwargs)#

Overloaded function.

makeVisualModel(nodeIndexer: samson.SBNodeIndexer, visualModelClassName: str, visualModelExtensionUUID: samson.SBUUID) -> samson.SBVisualModel

Make a visual model.

Parameters:

nodeIndexer (samson.SBNodeIndexer) – An indexer of nodes to which the visual model should be applied
visualModelClassName (str) – A class name of the visual model
visualModelExtensionUUID (samson.SBUUID) – UUID of the extension with this visual model

Returns:

A visual model or None if could not create one

Return type:

samson.SBVisualModel

Examples

Create a licorice visual model for all structural groups in the active document

>>> nodeIndexer = SAMSON.getNodes('n.t sg')
>>> visualModel = SAMSON.makeVisualModel(nodeIndexer = nodeIndexer, visualModelClassName = "SEMVisualModelLicorice", visualModelExtensionUUID = SBUUID("154ACCDA-8950-C6B2-7456-DAB6BA82AA5D"))
>>> if visualModel:
>>>     SAMSON.beginHolding("Add visual model")
>>>     SAMSON.hold(visualModel)
>>>     visualModel.create()
>>>     SAMSON.getActiveDocument().addChild(visualModel)
True
>>>     SAMSON.endHolding()

makeVisualModel(nodeIndexer: samson.SBNodeIndexer, visualModelName: str) -> samson.SBVisualModel

Make a visual model.

Parameters:

nodeIndexer (samson.SBNodeIndexer) – An indexer of nodes to which the visual model should be applied
visualModelName (str) – A public name of the visual model

Returns:

A visual model or None if could not create one

Return type:

samson.SBVisualModel

Examples

Create a licorice visual model for all structural groups in the active document

>>> nodeIndexer = SAMSON.getNodes('n.t sg')
>>> visualModel = SAMSON.makeVisualModel(nodeIndexer = nodeIndexer, visualModelName = "Licorice")
>>> if visualModel:
>>>     SAMSON.beginHolding("Add visual model")
>>>     SAMSON.hold(visualModel)
>>>     visualModel.create()
>>>     SAMSON.getActiveDocument().addChild(visualModel)
True
>>>     SAMSON.endHolding()

samson.SAMSON.minimize(nodeIndexer: samson.SBNodeIndexer, maximumNumberOfSteps: int, minimumNumberOfStepsInPlateau: int, energyDifferenceCriteria: samson.SBQuantity.unitsSI, printMinimizationInformationFrequency: int = 100, askUser: bool = False) → bool#

Minimize atoms in the nodeIndexer according to the provided criteria.

Parameters:

nodeIndexer (samson.SBNodeIndexer) – An indexer of nodes (atoms or nodes that have atoms in them) to which minimization should be applied.
maximumNumberOfSteps (int) – The maximum number of minimization steps.
minimumNumberOfStepsInPlateau (int) – The minimum number of consecutive steps sufficing the energy difference criteria.
energyDifferenceCriteria (samson.SBQuantity) – The energy difference threshold between two consecutive minimization steps.
printMinimizationInformationFrequency (int, default=100) – The frequency at which the minimization information should be printed. Set to 0 to disable. Note: printing information too often might decrease the performance.
askUser (bool, default=False) – Whether to ask user if some actions are required.

Return type:

bool

Examples

Minimize an atomic system in the active document

>>> nodeIndexer = SAMSON.getNodes('node.type atom');
>>> SAMSON.minimize(nodeIndexer, 1000, 25, SBQuantity.kJPerMol(0.5), 100, 100);

samson.SAMSON.printDataGraphState() → None#: Prints in the terminal the data graph state

samson.SAMSON.printFullMemoryUsage() → None#: Prints in the terminal the full memory usage

samson.SAMSON.printMemoryUsage() → None#: Prints in the terminal the memory usage

samson.SAMSON.printRendererState() → None#: Prints in the terminal the renderer state

samson.SAMSON.printUndoStack() → None#: Prints in the terminal the undo stack

samson.SAMSON.processEvents(excludeUserInputEvents: bool = True) → None#: Requests an update of the interface.

samson.SAMSON.redo() → None#: Redo one command.

See also

undo, isRedoing, isUndoing

samson.SAMSON.requestViewportUpdate() → None#: Requests a viewport update.

samson.SAMSON.runCommand(*args, **kwargs)#

Overloaded function.

runCommand(text: str) -> bool

Trigger the first found command with the given text.

Parameters:: text (str) – A name of a command (action), may include a path to this command (action) in the ribbon menu.
Returns:: True if an action was found, else False.
Return type:: bool

Examples

Run a command to add the Licorice visual model to the current selection or the active document if nothing is selected.

>>> SAMSON.runCommand('Licorice')
True

See also

getActionByText, getAction

runCommand(actionUUID: samson.SBUUID) -> bool

Trigger the action with the given action UUID.

Parameters:: actionUUID (samson.SBUUID) – A UUID of a command (action).
Returns:: True if an action was found, else False.
Return type:: bool

See also

getActionByText, getAction

samson.SAMSON.runPythonCode(codeString: str, raisePythonConsole: bool = False) → bool#

Executes Python code codeString in the Python Console.

Parameters:

codeString (str) – A string with Python code.
raisePythonConsole (bool, default=False) – Whether the Python Console should be raised.

Returns:

True if succeeded to launch the code.

Return type:

bool

See also

runPythonFile

samson.SAMSON.runPythonFile(fileName: str, raisePythonConsole: bool = False) → bool#

Executes Python script file fileName in the Python Console.

Parameters:

fileName (str) – A path to a Python script.
raisePythonConsole (bool, default=False) – Whether the Python Console should be raised.

Returns:

True if succeeded to launch the code.

Return type:

bool

See also

runPythonCode

samson.SAMSON.setActiveDocument(document: samson.SBDocument) → None#

Sets the active document.

Parameters:: document (samson.SBDocument) – The active document

Examples

Create a new document and sets it as active

>>> myDoc = SBDocument('My Document')
>>> myDoc.create()
>>> SAMSON.addDocument(myDoc)
>>> SAMSON.setActiveDocument(myDoc)
>>> # use the new clean document

See also

getActiveDocument

samson.SAMSON.setActiveDocumentFilter(filter: str) → None#

Sets the node filter of the active document in the Document View.

Parameters:: filter (str) – A node filter, use a Node Specification Language expression (SAMSON API: Node Specification Language).

Examples

Set a node filter in the Document View to residues.

>>> SAMSON.setActiveDocumentFilter('node.type residue')

See also

getActiveDocumentFilter

samson.SAMSON.setActiveEditor(classUUID: samson.SBUUID, extensionUUID: samson.SBUUID) → None#

Sets the current editor.

Parameters:

classUUID (samson.SBUUID) – UUID of the editor’s class.
extensionUUID (samson.SBUUID) – UUID of the editor’s extension.

samson.SAMSON.setActiveSelectionFilterByName(selectionFilterName: str) → bool#

Sets the active selection filter according to the given selection filter name.

Parameters:: selectionFilterName (str) – A name of the selection filter.
Returns:: True in case of the success.
Return type:: bool

Examples

Set the current selection filter to ‘Residues’.

>>> SAMSON.setCurrentSelectionFilter('Residues')
True

samson.SAMSON.setActiveStructuralModel(structuralModel: samson.SBStructuralModel) → None#

Sets the active structural model in the active document.

Parameters:: structuralModel (samson.SBStructuralModel) – A structural model in the active document

Examples

Set the 1st structural model in the active document as the active one

>>> structural_model_indexer = SAMSON.getNodes('node.type structuralModel')
>>> if structural_model_indexer.size:
...     SAMSON.setActiveStructuralModel(structural_model_indexer[0])

See also

getActiveStructuralModel

samson.SAMSON.setBusy(isBusy: bool) → None#: Notifies the user via the status bar that SAMSON is busy.

See also

setStatusMessage

samson.SAMSON.setProgressBarValue(value: int) → None#: Sets the value of the progress bar.

See also

showProgressBar, hideProgressBar, isProgressBarStopped

samson.SAMSON.setSimulationFlag(simulationFlag: bool) → None#

Sets the interactive simulation flag.

Parameters:: simulationFlag (bool) – The interactive simulation flag.

samson.SAMSON.setStatusMessage(message: str, time: int = 0) → None#: Shows a message in the status bar

samson.SAMSON.showProgressBar(name: str = '', minimum: int = 0, maximum: int = 0, minimumDurationInSeconds: float = 2.0, isCancellable: bool = True, cancelButtonText: str = 'Cancel') → None#

Shows the progress bar.

Parameters:

name (str, default='') – A name of the progress bar.
minimum (int, default=0) – A minimum value of the progress bar.
maximum (int, default=0) – A maximum value of the progress bar.
minimumDurationInSeconds (float, default=2.0) – A minimum duration in seconds.
isCancellable (bool, default=True) – Whether the progress bar can be canceled by the user.
cancelButtonText (str, default='Cancel') – A text of the Cancel button.

samson.SAMSON.showProperties(node: samson.SBNode) → bool#: Shows the properties widget of a node

samson.SAMSON.snap(*args, **kwargs)#

Overloaded function.

snap(x: int, y: int) -> tuple[int, int]

Returns the snapped mouse viewport displacement (x, y).

Parameters:

x (int) – x-coordinate displacement in the viewport
y (int) – y-coordinate displacement in the viewport

Returns:

Snapped x-, y-coordinate displacements in the viewport

Return type:

Tuple(int, int)

Examples

>>> xs, ys = SAMSON.snap(12, 23)

snap(x: int, y: int, pointInPlane: samson.SBPhysicalVector3) -> tuple[int, int]

Returns the snapped mouse viewport displacement (x, y) in the plane containing pointInPlane.

Parameters:

x (int) – x-coordinate displacement in the viewport
y (int) – y-coordinate displacement in the viewport
pointInPlane (samson.SBPosition3) – A point in the plane parallel to the viewport plane.

Returns:

Snapped x-, y-coordinate displacements in the viewport.

Return type:

Tuple(int, int)

Examples

>>> xs, ys = SAMSON.snap(12, 23, SBPosition3(SBQuantity.pm(0), SBQuantity.pm(0), SBQuantity.pm(100)))

snap(displacement: samson.SBQuantity.unitsSI) -> samson.SBQuantity.unitsSI

Returns the snapped translational (if the provided displacement is in length units) or angular (if the provided displacement is in dimensionless units) displacement if the snapping of translational/angular displacements is on, else it returns the unchanged displacement.

Parameters:: displacement (samson.SBQuantity) – Translational (if the provided displacement is in length units) or angular (if the provided displacement is in dimensionless units) displacement.
Returns:: Snapped translational (if the provided displacement is in length units) or angular (if the provided displacement is in dimensionless units) displacement.
Return type:: samson.SBQuantity

Examples

Get a snapped translational and angular displacements

>>> snapped_translational_displacement = SAMSON.snap(SBQuantity.angstrom(1.234))
>>> snapped_angular_displacement = SAMSON.snap(SBQuantity.degree(18.56))

snap(displacement: samson.SBPhysicalVector3) -> samson.SBPhysicalVector3

Returns the snapped displacement if the snapping of translational 3D displacements is on, else it returns the unchanged displacement.

Parameters:: displacement (samson.SBPosition3) – Translational displacement 3D vector.
Returns:: Snapped translational displacement 3D vector.
Return type:: samson.SBPosition3

Examples

Get a snapped translational and angular displacements

>>> snapped_displacement = SAMSON.snap(SBPosition3(SBQuantity.nm(0.12), SBQuantity.nm(1.2), SBQuantity.nm(12.3)))

snap(rotationMatrix: samson.SBPhysicalMatrix33) -> samson.SBPhysicalMatrix33

Returns the snapped rotation matrix if the snapping of angular displacements is on, else it returns the unchanged rotationMatrix.

Parameters:: displacement (samson.SBMatrix33) – A rotation matrix.
Returns:: A rotation matrix for the snapped angular displacement.
Return type:: samson.SBMatrix33

snap(transform: samson.SBSpatialTransform) -> samson.SBSpatialTransform

Returns the snapped spatial transform according to the translational and angular snapping parameters.

Parameters:: displacement (samson.SBSpatialTransform) – A spatial transform (includes translational and angular displacements).
Returns:: A spatial transform for the snapped translational and angular displacements.
Return type:: samson.SBSpatialTransform

samson.SAMSON.startSimulation() → None#: Starts interactive simulation.

See also

stopSimulation, toggleSimulation, getSimulationFlag, setSimulationFlag, minimize

samson.SAMSON.startTimer() → None#: Starts a new performance timer

samson.SAMSON.stopSimulation() → None#: Stops interactive simulation.

See also

startSimulation, toggleSimulation, getSimulationFlag, setSimulationFlag, minimize

samson.SAMSON.stopTimer() → list[samson.SBQuantity.unitsSI]#: Stops the top performance timer. Returns elapsed time and total time [in seconds]

samson.SAMSON.toggleSimulation() → None#: Toggles interactive simulation on and off.

See also

startSimulation, stopSimulation, getSimulationFlag, setSimulationFlag, minimize

samson.SAMSON.undo() → None#: Undo one command.

See also

redo, isRedoing, isUndoing

SAMSON

Contents

SAMSON#