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 Python API overview

Start scripting in SAMSON

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.

class samson.SAMSON.holding(self: samson.SAMSON.holding, arg0: str)#

Bases: pybind11_object

A context manager for holding undoable operations.

Calls internally SAMSON.beginHolding upon enter and SAMSON.endHolding upon exit.

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

Examples

>>> structuralModel = SBStructuralModel()
>>> with SAMSON.holding("Add structural model"):
>>>     SAMSON.hold(structuralModel)
>>>     structuralModel.create()
>>>     SAMSON.getActiveDocument().addChild(structuralModel)

See also

beginHolding, endHolding, hold

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

Add a document to the list of open documents.

Parameters:: document (samson.SBDocument) – The document to add

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

samson.SAMSON.addNewDocument(name: str) → samson.SBDocument#

Create a new document, add it to the list of open documents, set it as the active document, and return it.

This is a convenience function that internally creates a new document, adds it to the list of open documents using SAMSON.addDocument, and sets it as the active document using SAMSON.setActiveDocument.

Parameters:: name (str) – The document name.
Returns:: The newly created document.
Return type:: samson.SBDocument

Examples

Create a new document and sets it as active

>>> myDoc = SAMSON.addNewDocument('My document')
>>> # use the new clean document

samson.SAMSON.appIsInitialized(appUUID: samson.SBUUID, extensionUUID: samson.SBUUID = SBUUID('00000000-0000-0000-0000-000000000000')) → 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.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#

Begin holding.

Prefer using the context manager SAMSON.holding instead.

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: SupportsInt | SupportsIndex, height: SupportsInt | SupportsIndex, 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

Count active-document nodes selected by selectionString.

Traversal starts from the active document and is depth-first. visitString controls which nodes are visited; if a node does not satisfy it, neither that node nor its descendants are considered.

When includeDependencies is True, matching dependencies that are not descendants may also be counted, such as atoms referenced by an SBBond.

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 matching dependencies that are not descendants.

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

Count active-document nodes whose type matches nodeType.

Traversal starts from the active document and is depth-first. visitString controls which nodes are visited; if a node does not satisfy it, neither that node nor its descendants are considered.

When includeDependencies is True, matching dependencies that are not descendants may also be counted, such as atoms referenced by an SBBond.

Parameters:

nodeType (samson.SBNode.Type) – A type of nodes that should be counted.
selectedNodesOnly (bool, default=False) – If True, only nodes selected directly or through their parents are 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 matching dependencies that are not descendants.

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.deleteDocument(document: samson.SBDocument) → None#

Remove a document from the list of open documents and delete it.

This is a convenience function that internally removes the document from the list of open documents and erases it.

Parameters:: document (samson.SBDocument) – The document to remove and delete

Examples

Delete the active document

>>> document = SAMSON.getActiveDocument()
>>> SAMSON.deleteDocument(document)

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

See also

isHolding, enableHolding, beginHolding, hold, endHolding

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

See also

holding, isHolding, disableHolding, beginHolding, hold, endHolding

samson.SAMSON.endHolding() → None#

End holding.

Prefer using the context manager SAMSON.holding instead.

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: samson.SBValueMap) -> 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 (SBValueMap) – A value map with importer parameters.

See also

importFromFile

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

Overloaded function.

fetch(id: str, source: str = ‘’, folderPath: str = ‘’, importFlag: bool = True, preferredFolder: samson.SBFolder = None) -> None

Fetch a structure specified by identifier id from source source. This function allows you to fetch structures from the same sources as in “Home > Fetch” in SAMSON.

Parameters:

id (str) – Identifier to fetch. See the description of source and Home > Fetch in SAMSON for more information and examples.
source (str, default='') –

The source name, case insensitive.

If the source name is not provided, then the source will be guessed based on the identifier.

Loading files from some sources (‘alphafold’, ‘cod’, ‘mmcif’) will invoke pop-up import dialogs.

Available sources:

’alphafold’ :

Structures predicted by AlphaFold.

Source: AlphaFold Protein Structure Database.

Format: mmCIF (.cif).

Identifiers: UniProtKB entry, optionally, with AlphaFold-specific prefix and suffixes, e.g.: Q8I3H7 or AF-Q8I3H7-F1-model_v4

The prefix AF- is optional. You can specify the fragment id (e.g. -F1), if it’s not specified then -F1 will be added.

You can also specify the model version suffix (e.g., -model_v4), if not specified then -model_v4 will be added.

So, for example, Q8W3K0 will lead to AF-Q8W3K0-F1-model_v4.

Example: SAMSON.fetch('Q8I3H7', 'alphafold')

’cod’ :

Crystal structures.

Source: Crystallography Open Database (COD).

Format: CIF (.cif).

Identifiers: COD ID, e.g.: 1100118

Example: SAMSON.fetch('1100118', 'cod')

’esmfold’ :

Structures predicted by ESMFold.

Source: ESM Metagenomic Atlas.

Format: PDB (.pdb).

Identifiers: MGnify identifier, e.g.: MGYP000425902587

Example: SAMSON.fetch('MGYP000425902587', 'esmfold')

’iupac’ :

Generate 3D structure for the given IUPAC names. It uses OPSIN to convert IUPAC names into SMILES.

Format: SMI (.smi).

Identifiers: IUPAC name, e.g.: cyclohexane-1,2-diol

Example: SAMSON.fetch('cyclohexane-1,2-diol', 'iupac')

’mmcif’ :

Protein complexes or small molecules (ligands).

Source: RCSB Protein Data Bank.

Format: mmCIF (.cif).

Identifiers:

CCD ID for ligands, e.g.: 7KH, A1LU6

PDB ID, e.g.: 1YRF, pdb_00001af6

Load biological assemblies by appending its index to a PDB ID via a dot . (e.g.: .1.2.3). Examples: 8H2X.1 - download the bio-assembly 1 for 8H2X; 8H2X.1.3 - download bio-assemblies 1 and 3.

Example: SAMSON.fetch('1YRF', 'mmcif')

’mmtf’ :

Protein complexes.

Source: RCSB Protein Data Bank.

The MMTF format is not longer supported for new structures - as of July 2, 2024, RCSB PDB no longer serves PDB data in the MMTF format for structures deposited after this date.

Format: MMTF (.mmtf).

Identifiers: PDB ID, e.g.: 1YRF, pdb_00001af6

Example: SAMSON.fetch('1YRF', 'mmtf')

’pdb’ :

Protein complexes.

Source: RCSB Protein Data Bank.

Format: PDB (.pdb).

Identifiers: PDB ID, e.g.: 1YRF, pdb_00001af6

Load biological assemblies by appending its index to a PDB ID via a dot . (e.g.: .1.2.3). Examples: 8H2X.1 - download the bio-assembly 1 for 8H2X; 8H2X.1.3 - download bio-assemblies 1 and 3.

Example: SAMSON.fetch('1YRF', 'pdb')

’pubchem’:

Small molecules (ligands).

Source: PubChem based on their Compound Identifiers (CID).

Format: SDF (.sdf).

Identifiers: PubChem CID, e.g.: 2519

Example: SAMSON.fetch('2244', 'pubchem')

’smiles’ :

Generate 3D structures for the given SMILES codes. It uses RDKit library and the minimization integrated in SAMSON with the Universal Force Field.

Identifiers: SMILES code, e.g.: C1(C(CCCC1)O)O

Example: SAMSON.fetch('C1(C(CCCC1)O)O', 'smiles')
folderPath (str, default='') – A folder path where a downloaded file should be saved. If left empty then it will use the download folder from “Home > Fetch”.
importFlag (bool, default=True) – If True, import the downloaded file after it is fetched.
preferredFolder (samson.SBFolder or None, optional) – A folder node in SAMSON into which a system from the downloaded file should be imported.

Examples

Fetch structures from different sources and load them in SAMSON.

>>> SAMSON.fetch('1YRF', 'pdb')
>>> SAMSON.fetch('A1LU6', 'mmcif')
>>> SAMSON.fetch('Q8I3H7', 'alphafold')
>>> SAMSON.fetch('MGYP000425902587', 'esmfold')
>>> SAMSON.fetch('2244', 'pubchem')
>>> SAMSON.fetch('cyclohexane-1,2-diol', 'iupac')
>>> SAMSON.fetch('C1(C(CCCC1)O)O', 'smiles')
>>> SAMSON.fetch('1100118', 'cod')

fetch(ids: collections.abc.Sequence[str], source: str = ‘’, folderPath: str = ‘’, importFlag: bool = True, preferredFolder: samson.SBFolder = None) -> None

Fetch multiple structures specified by the identifier list ids from source source. This function allows you to fetch structures from the same sources as in “Home > Fetch” in SAMSON.

Parameters:

ids (list[str]) – Identifiers to fetch. See the description of source above and Home > Fetch in SAMSON for more information and examples.
source (str, default='') –

The source name, case insensitive.

If the source name is not provided, then the source will be guessed based on the first non-empty identifier in the list.

Loading files from some sources (‘alphafold’, ‘cod’, ‘mmcif’) will invoke pop-up import dialogs.

Available sources: ‘alphafold’, ‘cod’, ‘esmfold’, ‘iupac’, ‘mmcif’, ‘mmtf’, ‘pdb’, ‘pubchem’, ‘smiles’

See the description of sources above.
folderPath (str, default='') – A folder path where a downloaded file should be saved. If left empty then it will use the download folder from “Home > Fetch”.
importFlag (bool, default=True) – If True, import the downloaded files after they are fetched.
preferredFolder (samson.SBFolder or None, optional) – A folder node in SAMSON into which a system from the downloaded file should be imported.

Examples

Fetch structures from different sources and load them in SAMSON.

>>> SAMSON.fetch(['1YRF', '2AZ8'], 'pdb')
>>> SAMSON.fetch(['2244', '2259'], 'pubchem')

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:: Matching action, or None if no action was found for actionUUID.
Return type:: samson.SBAction or None

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:: Matching action, or None if no action was found.
Return type:: samson.SBAction or None

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.getActiveAsset() → samson.SBAsset#: Returns the active asset

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#

Return the active document.

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#

Return the active structural model in the active document.

Returns:: The active structural model, or None if the active document has no active structural model.
Return type:: samson.SBStructuralModel or None

Examples

Get the active structural model in the active document.

>>> active_structural_model = SAMSON.getActiveStructuralModel()

See also

setActiveStructuralModel

samson.SAMSON.getAnimationNames() → list[str]#: Returns a list of public names of animations

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

samson.SAMSON.getAtom(x: SupportsInt | SupportsIndex, y: SupportsInt | SupportsIndex) → 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: SupportsInt | SupportsIndex, y: SupportsInt | SupportsIndex) → 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: SupportsInt | SupportsIndex, label: str, choices: collections.abc.Sequence[str], toolTips: collections.abc.Sequence[str]) → tuple[bool, int]#

Open a modal dialog to choose an item from a list.

Parameters:

dialogTitle (str) – A title of the pop-up dialog.
currentIndex (int) – Index selected when the dialog opens.
label (str) – Description label shown in the dialog.
choices (list[str]) – Choices shown in the dialog.
toolTips (list[str]) – Tooltip text for the corresponding choices.

Returns:

A tuple (status, index). If OK was clicked, status is True and index is the chosen index. If Cancel was clicked, status is False and index is currentIndex.

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[bool, samson.SBColor]#

Open a modal dialog to choose a color.

Parameters:

dialogTitle (str, default='Choose a color') – A title of the pop-up dialog.
color (samson.SBColor, default=SBColor()) – Color selected when the dialog opens.

Returns:

A tuple (status, color). If OK was clicked, status is True and color is the chosen color. If Cancel was clicked, status is False and color is the original color value.

Return type:

tuple[bool, samson.SBColor]

Examples

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

See also

getPaletteFromUser

samson.SAMSON.getColorSchemeNames() → list[str]#: Returns a list of public names of color schemes

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: typing.SupportsInt | typing.SupportsIndex) -> samson.SBQuantity.unitsSI

Returns the covalent radius of a periodic table element for a specific bond type.

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: SupportsFloat | SupportsIndex, minimum: SupportsFloat | SupportsIndex, maximum: SupportsFloat | SupportsIndex, singleStep: SupportsFloat | SupportsIndex = 1.0, prefix: str = '', suffix: str = '', decimals: SupportsInt | SupportsIndex = 2) → tuple[bool, float]#

Open a modal dialog to choose a floating-point value.

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 (status, value). If OK was clicked, status is True and value is the chosen value. If Cancel was clicked, status is False and value 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: collections.abc.Sequence[str], currentValues: tuple[SupportsFloat | SupportsIndex, SupportsFloat | SupportsIndex], minValueInterval: tuple[SupportsFloat | SupportsIndex, SupportsFloat | SupportsIndex], maxValueInterval: tuple[SupportsFloat | SupportsIndex, SupportsFloat | SupportsIndex], singleStep: tuple[SupportsFloat | SupportsIndex, SupportsFloat | SupportsIndex] = (1.0, 1.0), prefix: str = '', suffix: str = '') → tuple#

Open a modal dialog to choose a floating-point interval.

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[float, float], default=(1, 1)) – Step values for the left and right spin boxes.
prefix (str, default='') – A prefix shown in the spin box.
suffix (str, default='') – A suffix shown in the spin box.

Returns:

A tuple (status, interval). If OK was clicked, status is True and interval is the chosen interval. If Cancel was clicked, status is False and interval 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[bool, samson.SBElement.ElementType]#

Open a modal dialog to choose a periodic table element.

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 (status, element). If OK was clicked, status is True and element is the selected element. If Cancel was clicked, status is False and element is SBElement.ElementType.Unknown.

Return type:

tuple[bool, samson.SBElement.ElementType]

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: collections.abc.Sequence[samson.SBElement.ElementType] = []) → tuple[bool, list[samson.SBElement.ElementType]]#

Open a modal dialog to choose multiple periodic table elements.

Parameters:

dialogTitle (str, default='Select elements') – A title of the pop-up dialog.
currentElement (list[samson.SBElement.ElementType], optional) – Elements selected when the dialog opens.

Returns:

A tuple (status, elements). If OK was clicked, status is True and elements is the selected element list. If Cancel was clicked, status is False and elements is an empty list.

Return type:

tuple[bool, list[samson.SBElement.ElementType]]

Examples

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

See also

getElementFromUser

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

Open a modal dialog to choose a file.

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 (status, fileName). If OK was clicked, status is True and fileName is the chosen file name. If Cancel was clicked, status is False and fileName 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[bool, list[str]]#

Open a modal dialog to choose multiple files.

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 (status, fileNames). If OK was clicked, status is True and fileNames is the chosen list of file names. If Cancel was clicked, status is False and fileNames is an empty list.

Return type:

tuple[bool, list[str]]

Examples

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

samson.SAMSON.getGPUInfo() → str#: Returns a string with the user’s GPU name

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: SupportsInt | SupportsIndex, minimum: SupportsInt | SupportsIndex, maximum: SupportsInt | SupportsIndex, singleStep: SupportsInt | SupportsIndex = 1, prefix: str = '', suffix: str = '') → tuple[bool, int]#

Open a modal dialog to choose an integer value.

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:

A tuple (status, value). If OK was clicked, status is True and value is the chosen value. If Cancel was clicked, status is False and value is currentValue.

Return type:

tuple[bool, int]

Examples

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

samson.SAMSON.getIntegerIntervalFromUser(dialogTitle: str, labelsText: collections.abc.Sequence[str], currentValues: tuple[SupportsInt | SupportsIndex, SupportsInt | SupportsIndex], minValueInterval: tuple[SupportsInt | SupportsIndex, SupportsInt | SupportsIndex], maxValueInterval: tuple[SupportsInt | SupportsIndex, SupportsInt | SupportsIndex], singleStep: tuple[SupportsInt | SupportsIndex, SupportsInt | SupportsIndex] = (1, 1), prefix: str = '', suffix: str = '') → tuple#

Open a modal dialog to choose an integer interval.

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[int, int], default=(1, 1)) – Step values for the left and right spin boxes.
prefix (str, default='') – A prefix shown in the spin box.
suffix (str, default='') – A suffix shown in the spin box.

Returns:

A tuple (status, interval). If OK was clicked, status is True and interval is the chosen interval. If Cancel was clicked, status is False and interval 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.getInteractionModelNames() → list[str]#: Returns a list of public names of interaction models

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

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

Overloaded function.

getItemFromUser(dialogTitle: str, label: str, items: collections.abc.Sequence[str], currentIndex: typing.SupportsInt | typing.SupportsIndex = 0) -> tuple[bool, str]

Open a modal dialog to choose an item by text.

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 (status, itemText). If OK was clicked, status is True and itemText is the chosen item text. If Cancel was clicked, status is False and itemText is an empty string.

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: typing.SupportsInt | typing.SupportsIndex, label: str, items: collections.abc.Sequence[str]) -> tuple[bool, int]

Open a modal dialog to choose an item by index.

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 (status, index). If OK was clicked, status is True and index is the chosen item index. If Cancel was clicked, status is False and index is -1.

Return type:

tuple[bool, int]

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.getMinimizationFlag() → bool#

Returns True when interactive minimization is on.

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

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

Return the current mouse position in viewport coordinates.

Returns:: The current (x, y) mouse position in 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#

Return the next available node name for the requested scope.

Parameters:

type (samson.SBNode.Type) – Node type used to test name availability.
prefix (str, default='') – Prefix for the generated name.
suffix (str, default='') – Suffix for the generated name.
parentNode (samson.SBNode or None, optional) – Parent node used to scope the lookup. Pass None to search in the active document.

Returns:

The next available node name that matches the requested type, prefix, and suffix.

Return type:

str

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

Return the node at (x, y) in the viewport that matches selectionFilter.

Parameters:

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

Returns:

Matching node at the requested viewport position, or None if no node matches the filter at that position.

Return type:

samson.SBNode or None

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: typing.SupportsInt | typing.SupportsIndex, y: typing.SupportsInt | typing.SupportsIndex, width: typing.SupportsInt | typing.SupportsIndex, height: typing.SupportsInt | typing.SupportsIndex, selectionFilter: str = ‘*’, deepSelectionFlag: bool = False) -> samson.SBNodeIndexer

Return nodes inside a viewport rectangle that match selectionFilter.

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.
selectionFilter (str, default='*') – A Node Specification Language expression (SAMSON API: Node Specification Language).
deepSelectionFlag (bool, default=False) – Whether to include nodes hidden behind visible geometry. If True, nodes behind the rectangle can still be returned even when they are not currently visible because of depth-of-field, fog, or other viewport effects.

Returns:

Indexer containing the matching nodes.

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

Return active-document nodes selected by selectionString.

Traversal starts from the active document and is depth-first. visitString controls which nodes are visited; if a node does not satisfy it, neither that node nor its descendants are considered. selectionString controls which visited nodes are added to the returned indexer.

When includeDependencies is True, the result may also include matching dependencies that are not descendants, such as atoms referenced by an SBBond.

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 matching dependencies that are not descendants.

Returns:

Node indexer containing the matching nodes.

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

Append active-document nodes selected by selectionString to nodeIndexer.

When includeDependencies is True, the destination may also receive matching dependencies that are not descendants, such as atoms referenced by an SBBond.

Parameters:

nodeIndexer (samson.SBNodeIndexer) – Destination indexer. It is not cleared by this 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 matching dependencies that are not descendants.

Notes

The nodeIndexer argument is not cleared when entering this function.

Examples

Collect all residues from the active document into an existing indexer:

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

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

Return active-document nodes whose type matches nodeType.

Traversal starts from the active document and is depth-first. visitString controls which nodes are visited; if a node does not satisfy it, neither that node nor its descendants are considered.

When includeDependencies is True, the result may also include matching dependencies that are not descendants, such as atoms referenced by an SBBond.

Parameters:

nodeType (samson.SBNode.Type) – A type of nodes that should be collected.
selectedNodesOnly (bool, default=False) – If True, only nodes selected directly or through their parents are 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 matching dependencies that are not descendants.

Returns:

Node indexer containing the matching nodes.

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

Append active-document nodes whose type matches nodeType to nodeIndexer.

Traversal starts from the active document and is depth-first. visitString controls which nodes are visited; if a node does not satisfy it, neither that node nor its descendants are considered.

When includeDependencies is True, the destination may also receive matching dependencies that are not descendants, such as atoms referenced by an SBBond.

Parameters:

nodeIndexer (samson.SBNodeIndexer) – Destination indexer. It is not cleared by this function.
nodeType (samson.SBNode.Type) – A type of nodes that should be collected.
selectedNodesOnly (bool, default=False) – If True, only nodes selected directly or through their parents are 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 matching dependencies that are not descendants.

Notes

The nodeIndexer argument 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[bool, samson.SBPalette]#

Open a modal dialog to choose a color palette.

Parameters:

dialogTitle (str, default='Choose a color palette') – A title of the pop-up dialog.
defaultColorPalette (samson.SBPalette or None, optional) – Palette selected when the dialog opens. Pass None to use no explicit default palette.

Returns:

A tuple (status, palette). If OK was clicked, status is True and palette is the chosen color palette. If Cancel was clicked, status is False and palette is None.

Return type:

tuple[bool, samson.SBPalette | None]

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[bool, str]#

Open a modal dialog to choose a filesystem path.

Parameters:

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

Returns:

A tuple (status, path). If OK was clicked, status is True and path is the chosen path. If Cancel was clicked, status is False and path 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[bool, str]#

Open a modal dialog to request a short string.

Parameters:

dialogTitle (str) – A title of the pop-up dialog.
placeholderText (str) – Placeholder text shown in the input field.

Returns:

A tuple (status, text). If OK was clicked, status is True and text is the user-provided string. If Cancel was clicked, status is False and text is an empty string.

Return type:

tuple[bool, str]

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

Return the proxy of a class.

Parameters:

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

Returns:

Matching proxy, or None if no proxy was found.

Return type:

samson.SBProxy or None

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]#

Return all proxies corresponding to classType.

Parameters:: classType (samson.SBClass.Type) – Class type to query.
Returns:: Proxies that match classType.
Return type:: list[samson.SBProxy]

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[bool, str]#

Open a modal dialog to choose an output file.

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:

A tuple (status, fileName). If OK was clicked, status is True and fileName is the chosen file name. If Cancel was clicked, status is False and fileName is an empty string.

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.getSelectorNames() → list[str]#: Returns a list of public names of selectors

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.getStateUpdaterNames() → list[str]#: Returns a list of public names of state updaters

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

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

Open a modal dialog to choose a string.

Parameters:

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

Returns:

A tuple (status, text). If OK was clicked, status is True and text is the user-provided string. If Cancel was clicked, status is False and text 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.getUserAcademicFlag() → bool#: Returns True when the user is an academic

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.getVisualModelNames() → list[str]#: Returns a list of public names of visual models

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

Return whether the active document has a node selected by selectionString.

Traversal starts from the active document and is depth-first. visitString controls which nodes are visited; if a node does not satisfy it, neither that node nor its descendants are considered.

When includeDependencies is True, dependencies that are not descendants may also be checked, such as atoms referenced by an SBBond.

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 matching dependencies that are not descendants.

Returns:

True if at least one matching node exists, otherwise False.

Return type:

bool

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

Return whether the active document has a node of type nodeType.

Traversal starts from the active document and is depth-first. visitString controls which nodes are visited; if a node does not satisfy it, neither that node nor its descendants are considered.

When includeDependencies is True, dependencies that are not descendants may also be checked, such as atoms referenced by an SBBond.

Parameters:

nodeType (samson.SBNode.Type) – A type of nodes that should be checked for.
selectedNodesOnly (bool, default=False) – If True, only nodes selected directly or through their parents are 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 matching dependencies that are not descendants.

Returns:

True if at least one matching node exists, otherwise False.

Return type:

bool

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: collections.abc.Sequence[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: samson.SBValueMap, 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 (SBValueMap) – A value map with importer parameters.
preferredFolder (samson.SBFolder, default=None) – A folder into which the system from the file should be imported.

See also

fetch, exportToFile

importFromFile(fileNameList: collections.abc.Sequence[str], parameters: samson.SBValueMap, 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 (SBValueMap) – A value map with importer parameters.
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.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

holding, disableHolding, enableHolding, beginHolding, hold, endHolding

samson.SAMSON.isProgressBarStopped() → bool#

Returns True when the progress bar is stopped.

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

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: typing.SupportsFloat | typing.SupportsIndex, animationClassName: str, animationExtensionUUID: samson.SBUUID, animationParameterMap: samson.SBValueMap = <SBValueMap: size=0>) -> 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
animationParameterMap (samson.SBValueMap) – The value map with parameters for the animation

Returns:

An animation node, or None if SAMSON cannot create one.

Return type:

samson.SBAnimation

makeAnimation(name: str, nodeIndexer: samson.SBNodeIndexer, currentFrame: typing.SupportsFloat | typing.SupportsIndex, animationName: str, animationParameterMap: samson.SBValueMap = <SBValueMap: size=0>) -> 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
animationParameterMap (samson.SBValueMap) – The value map with parameters for the animation

Returns:

An animation node, or None if SAMSON cannot create one.

Return type:

samson.SBAnimation

samson.SAMSON.makeInteractionModel(dynamicalModel: samson.SBParticleSystem, interactionModelClassName: str, interactionModelExtensionUUID: samson.SBUUID = SBUUID("00000000-0000-0000-0000-000000000000"), interactionModelParameterMap: samson.SBValueMap = <SBValueMap: size=0>) → 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
interactionModelParameterMap (samson.SBValueMap) – The value map with parameters for the interaction model

Returns:

An interaction model, or None if SAMSON cannot create one.

Return type:

samson.SBInteractionModel

samson.SAMSON.makeNeighborSearch(dynamicalModel: samson.SBParticleSystem, cutoffDistance: samson.SBQuantity.unitsSI, neighborSearchClassName: str, neighborSearchExtensionUUID: samson.SBUUID = SBUUID('00000000-0000-0000-0000-000000000000')) → 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 algorithm, or None if SAMSON cannot create one.

Return type:

samson.SBNeighborSearch

samson.SAMSON.makePropertyModel(nodeIndexer: samson.SBNodeIndexer, propertyModelClassName: str, propertyModelExtensionUUID: samson.SBUUID = SBUUID("00000000-0000-0000-0000-000000000000"), propertyModelParameterMap: samson.SBValueMap = <SBValueMap: size=0>) → samson.SBPropertyModel#: Make a property model

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

Overloaded function.

makeSelector(selectorClassName: str, selectorExtensionUUID: samson.SBUUID, selectorParameterMap: samson.SBValueMap = <SBValueMap: size=0>) -> samson.SBNodeSelector

Make a selector.

Parameters:

selectorClassName (str) – A class name of the selector
selectorExtensionUUID (samson.SBUUID) – UUID of the extension with this selector
selectorParameterMap (samson.SBValueMap) – The value map with parameters for the selector

Returns:

A selector, or None if SAMSON cannot create one.

Return type:

samson.SBNodeSelector

makeSelector(selectorName: str, selectorParameterMap: samson.SBValueMap = <SBValueMap: size=0>) -> samson.SBNodeSelector

Make a selector.

Parameters:

selectorName (str) – A name of the selector
selectorParameterMap (samson.SBValueMap) – The value map with parameters for the selector

Returns:

A selector, or None if SAMSON cannot create one.

Return type:

samson.SBNodeSelector

samson.SAMSON.makeSimulator(nodeIndexer: samson.SBNodeIndexer, interactionModelClassName: str, interactionModelExtensionUUID: samson.SBUUID, interactionModelParameterMap: samson.SBValueMap, stateUpdaterClassName: str, stateUpdaterExtensionUUID: samson.SBUUID = SBUUID("00000000-0000-0000-0000-000000000000"), stateUpdaterParameterMap: samson.SBValueMap = <SBValueMap: size=0>) → 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
interactionModelParameterMap (samson.SBValueMap) – The value map with parameters for the interaction model
stateUpdaterClassName (str) – A class name of the state updater
stateUpdaterExtensionUUID (samson.SBUUID) – UUID of the extension with this state updater
stateUpdaterParameterMap (samson.SBValueMap) – The value map with parameters for the state updater

Returns:

A simulator, or None if SAMSON cannot create one.

Return type:

samson.SBSimulator

samson.SAMSON.makeStateUpdater(dynamicalModel: samson.SBParticleSystem, interactionModel: samson.SBInteractionModelParticleSystem, stateUpdaterClassName: str, stateUpdaterExtensionUUID: samson.SBUUID = SBUUID("00000000-0000-0000-0000-000000000000"), stateUpdaterParameterMap: samson.SBValueMap = <SBValueMap: size=0>) → 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
stateUpdaterParameterMap (samson.SBValueMap) – The value map with parameters for the state updater

Returns:

A state updater, or None if SAMSON cannot create one.

Return type:

samson.SBStateUpdater

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

Overloaded function.

makeVisualModel(nodeIndexer: samson.SBNodeIndexer, visualModelClassName: str, visualModelExtensionUUID: samson.SBUUID, visualModelParameterMap: samson.SBValueMap = <SBValueMap: size=0>) -> 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
visualModelParameterMap (samson.SBValueMap) – The value map with parameters for the visual model

Returns:

A visual model, or None if SAMSON cannot 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, visualModelParameterMap: samson.SBValueMap = <SBValueMap: size=0>) -> 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
visualModelParameterMap (samson.SBValueMap) – The value map with parameters for the visual model

Returns:

A visual model, or None if SAMSON cannot 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: SupportsInt | SupportsIndex, minimumNumberOfStepsInPlateau: SupportsInt | SupportsIndex, energyDifferenceCriteria: samson.SBQuantity.unitsSI, printMinimizationInformationFrequency: SupportsInt | SupportsIndex = 100, askUser: bool = False) → bool#

Minimize atoms in 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.

Returns:

True if minimization completed successfully, else False.

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, False);

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

Overloaded function.

openPreferences(pageName: str) -> bool

Open Preferences at the page named pageName.

Parameters:: pageName (str) – Name of the page to open. If it is empty, Preferences opens at the default page. If multiple pages share the same name, provide a full path such as Editors > Add.
Returns:: True if the requested page was found, else False.
Return type:: bool

Examples

>>> SAMSON.openPreferences("Anti-aliasing")
>>> SAMSON.openPreferences("Editors > Add")

openPreferences(uuid: samson.SBUUID) -> bool

Open Preferences at the page associated with uuid.

Parameters:: uuid (samson.SBUUID) – UUID of an app, editor, or other class that exposes settings in Preferences. If uuid is not valid, Preferences opens at the default page.
Returns:: True if the requested page was found, else False.
Return type:: bool

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.removeDocument(document: samson.SBDocument) → None#

Remove a document from the list of open documents.

Parameters:: document (samson.SBDocument) – The document to remove

Examples

Removes the active document

>>> document = SAMSON.getActiveDocument()
>>> SAMSON.removeDocument(document)
>>> document.erase()                   # delete the document

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

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

Overloaded function.

runCommand(text: str) -> bool

Trigger the first matching command.

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

runCommand(actionUUID: samson.SBUUID) -> bool

Trigger the action with the given UUID.

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

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

Execute Python code 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 the code was launched successfully, else False.

Return type:

bool

See also

runPythonFile

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

Execute a Python script file 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 the script was launched successfully, else False.

Return type:

bool

See also

runPythonCode

samson.SAMSON.select(text: str) → bool#

Select nodes in the active document based on the given NSL string.

Parameters:: text (str) – An NSL string.
Returns:: True if the NSL expression was valid and the selection was applied, else False.
Return type:: bool

Examples

Select all receptors in the active document using NSL:

>>> SAMSON.select('node.category receptor')

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

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#

Set the active selection filter by name.

Parameters:: selectionFilterName (str) – A name of the selection filter.
Returns:: True if the selection filter was set successfully, else False.
Return type:: bool

Examples

Set the current selection filter to ‘Residues’.

>>> SAMSON.setActiveSelectionFilterByName('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.setMinimizationFlag(minimizationFlag: bool) → None#

Sets the interactive minimization flag.

Parameters:: minimizationFlag (bool) – The interactive minimization flag.

samson.SAMSON.setProgressBarValue(value: SupportsInt | SupportsIndex) → 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: SupportsInt | SupportsIndex = 0) → None#: Shows a message in the status bar

samson.SAMSON.showProgressBar(name: str = '', minimum: SupportsInt | SupportsIndex = 0, maximum: SupportsInt | SupportsIndex = 0, minimumDurationInSeconds: SupportsFloat | SupportsIndex = 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: typing.SupportsInt | typing.SupportsIndex, y: typing.SupportsInt | typing.SupportsIndex) -> tuple[int, int]

Return the snapped mouse displacement in viewport coordinates.

Parameters:

x (int) – Horizontal displacement in viewport coordinates.
y (int) – Vertical displacement in viewport coordinates.

Returns:

The snapped (x, y) displacement in viewport coordinates.

Return type:

tuple[int, int]

Examples

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

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

Return the snapped mouse displacement in the plane containing pointInPlane.

Parameters:

x (int) – Horizontal displacement in viewport coordinates.
y (int) – Vertical displacement in viewport coordinates.
pointInPlane (samson.SBPosition3) – Point in the plane parallel to the viewport plane.

Returns:

The snapped (x, y) displacement in viewport coordinates.

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

Return the snapped rotation matrix when angular snapping is enabled.

Parameters:: rotationMatrix (samson.SBMatrix33) – Rotation matrix to snap.
Returns:: Snapped rotation matrix, or the input matrix when angular snapping is disabled.
Return type:: samson.SBMatrix33

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

Return the snapped spatial transform according to the translational and angular snapping settings.

Parameters:: transform (samson.SBSpatialTransform) – Spatial transform that includes translational and angular displacements.
Returns:: Snapped spatial transform.
Return type:: samson.SBSpatialTransform

samson.SAMSON.startMinimization() → None#: Starts interactive minimization.

See also

stopMinimization, toggleMinimization, getMinimizationFlag, setMinimizationFlag, minimize

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.stopMinimization() → None#: Stops interactive minimization.

See also

startMinimization, toggleMinimization, getMinimizationFlag, setMinimizationFlag, minimize

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.toggleMinimization() → None#: Toggles interactive minimization on and off.

See also

startMinimization, stopMinimization, getMinimizationFlag, setMinimizationFlag, minimize

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#