Skip to content

Building molecules

SAMSON provides a number of powerful ways to build and modify molecular systems thanks to various editors and apps.

SAMSON provides a variety of extensions that can be used for building and modifying of molecules and system of molecules, for example:

You can try the following interactive tutorial in SAMSON (Help > Tutorials): "Building with atoms".

What you will learn from this tutorial:

What is not covered in this tutorial:

For how to build objects with the help of Python Scripting, please, refer to the Python Scripting Guide.

Let's first have a quick look on the main builder features.

Quick look on builder features#

Let's take a quick look at the main builder features in SAMSON.

SAMSON provides you with the possibility to build using individual atoms from the Asset Browser (with a quick access to H, C, N, O atoms at the bottom of the Asset Browser)...

Building with atoms

or using the Periodic table...

Building with atoms from Periodic Table

or by assembling assets.

Building with assets

Assets can be anything: atoms, functional groups, rings, fragments, radicals, whole molecules, proteins, nanoparticles, 2D materials, etc. You can assemble them in the document to rapidly set up complex models for analysis and simulation.

Whether you're constructing with individual atoms or with assets, the builder has several cool features to assist you, as shown above, in particular, it has options to:

  • predict fragments orientations;
  • prevent implausible substitutions: acceptable substitutions or additions have a green overlay, while forbidden ones have a red overlay;
  • automatically adjust hydrogens;
  • merge overlapping atoms.

You can control in the Preferences whether you want to follow these recommendations or override them (see Structural model preferences).

By pressing and holding the Shift key, you can choose which atom and bond in the asset are used to replace the atoms and bonds you click in the document:

Choosing the substitution atom

Asset Browser#

The Asset Browser (1) provides access to the assets (molecule fragments, etc.) included by default in SAMSON together with the assets you can obtain from SAMSON Connect.

  1. Interface > Assets, , : Ctrl+4, : Cmd+4

Asset browser

Try going through various folders in the Asset Browser to see what is available. To search for available assets, use the "Filter assets..." at the top of the Asset Browser.

Asset browser

To search for available assets, use the "Filter assets..." at the top of the Asset Browser.

To change the size of images and text in the Asset Browser, you can zoom in / zoom out using Ctrl and mouse wheel or use commands with the magnifying glass with "+" and "-" icons.

To switch between the grid and the list view, use the right-most buttons (list mode, grid mode) at the bottom of the Asset Browser.

If you would like to make your library of fragments/molecules available in SAMSON, contact us.

Prerequisites#

Before going through this tutorial, we recommend going through the interactive tutorials (1) integrated into SAMSON that will guide you through the basic operations. Specifically, we recommend going through the following interactive tutorials:

  1. Help > Tutorials
  • "Working with documents"
  • "Selecting in the Viewport"
  • "Building with atoms"
  • "Moving objects in the Viewport"

You can try the following interactive tutorials in SAMSON

You can also check the following sections of the User Guide:

In this section, we will partly cover what is covered in the "Building with atoms" interactive tutorial as well.

Preferences#

Building in SAMSON is done using the Add editor which has various options that can be checked in Preferences > Editors > Add.

Go to Preferences (Interface > Preferences) and there in the Editors > Add section, and make sure that the "Adjust hydrogens when adding fragments..." option is checked.

Preferences of the Add editor

Adjust hydrogens when adding fragments... - if this option is checked, then hydrogens will be adjusted automatically (as best as possible) when adding atoms/fragments, linking atoms/fragments, editing bond order, and changing atom formal charge based on valences.

Automatically orient fragments on substitution - if this option is checked, then when trying to connect a fragment to an existing molecule it will be positioned (as best as possible) such that its atoms won't overlap with the molecule's atoms.

Merge neighboring atoms - if this option is checked, then when trying to connect a fragment to an existing molecule and some fragment atoms appear to be close enough to the molecule's atoms then they will be merged together as well as the substitution atom.

Prevent unexpected substitutions - if this option is checked, then it prevents implausible substitutions: acceptable substitutions or additions have a green overlay, while forbidden ones have a red overlay

Select fragments after adding them - if checked, selects the just added fragment.

Randomize orientations - if checked, randomizes orientation of fragments placed separately. For example, when adding water or methane molecules this will randomize molecule's orientation.

Create new structural models when adding non-covalent fragments - if checked, a new structural model will be created for each added fragment that is not covalently linked to any other molecule in the document.

Building with atoms#

Before proceeding, please check the Preferences section and make sure that options are checked as shown there.

Constructing a molecule from atoms#

Let's start by constructing a simple N-acetyl group.

Building N-Acetyl group

The building in SAMSON is done thanks to the Add editor Add editor (1). With the Add editor, you can build with atoms and available assets (fragments, etc.). When you activate the Add editor, you should see the current active fragment in the Viewport, and it will also open the Asset Browser with all the available assets. You have quick access to some common atoms, rings, the Periodic table with all atoms in the Asset Browser.

  1. Shortcut: A, the left-side menu in the Viewport

In the top-left corner of the viewport, you should see the Snapping options (translational and angular displacement snapping) - they might influence how the fragments are added and positioned. Snapping can be useful, for example, when you need to place fragments on a grid with a specific distance between them. Just set both of them to Off for the sake of this tutorial.

The Add editor's snapping options

Let's start by adding a Carbon atom: click on C (Add carbon) in the Asset Browser and click anywhere in the Viewport.

Add carbon atom

With the "Adjust hydrogens..." option checked (see Preferences) it should automatically add the necessary hydrogens. So, in this case, it should become CH4.

Let's now connect another Carbon to it. There are two main modes to connect atoms/fragments:

1. Substitute an atom: hover above the atom that you want to substitute and click on it.

Note

When adding by substitution an atom or a fragment, SAMSON tries to position the newly added atom or fragment with taking into account covalent radii of atoms. You can see it on the gif below.

Adding carbon atom by substitution

2. Create a bond between atoms: hover above the atom to which you would like to attach the fragment, press on the atom, and hold, then move your mouse away and release it once it is at a sufficient (bond-like) distance.

Adding carbon atom via bond

Try these modes to add another Carbon.

Note

You can always undo commands by clicking Ctrl/Cmd + Z (Edit > Undo) and redo by clicking Ctrl/Cmd + Y (Edit > Redo).

When building you can always switch on the interactive minimization in SAMSON (shortcut: Z, Edit > Minimize). You can build fragments, connect them while the interactive minimization is running. Now, switch on the interactive minimization by pressing Z. This should minimize the system. To switch it off press Z once more.

Let's now add Nitrogen and Oxygen atoms.

Adding nitrogen and oxygen atoms

When the interactive minimization, you can see how the molecule is minimized while you build it.

Note

If you need to use other atom types, click on the Periodic table Periodic table (1) and choose an atom from there simply by clicking on it.

  1. , : Ctrl+5, : Cmd+5, Interface > Periodic table, or Periodic table in the Asset Browser

We are almost done, now we just need to change the bond order between the oxygen atom and a carbon atom bonded to it.

Changing bond order#

You can easily modify interactively the bond order using the Edit bonds Bond editor editor (shortcut: B, the left-side menu in the Viewport). Click on this editor Bond editor to activate it and hover above the bond that you would like to modify. Click on "-" or "+" to change the bond order.

Changing bond order

As you can see the N-C bond order also changed (to about 1.4) due to the usage of the Universal Force Field in the interactive minimizer.

Note

Depending on the file format in which you chose to save, it might be saved as a single bond. See the below how to modify the bond order using the Inspector.

You can also modify the bond order and bond type by selecting the bond and going to the Inspector (1). But note that in this case, hydrogens will not be adjusted automatically.

  1. Interface > Inspector, , : Ctrl+2, : Cmd+2

Inspect bond order

Changing atom formal charge#

If you want to modify formal charges of atoms, you can use the Edit charges Charge editor editor (shortcut: C, the left-side menu in the Viewport). Click on this editor Charge editor to activate it and hover above an atom for which you would like to modify the formal charge and click on "-" or "+" to change it.

Changing atom formal charge

Building with fragments#

Before proceeding, please check the Preferences section and make sure that options are checked as shown there.

To build from fragments you can use:

Using constructed fragments for building#

You can use a molecule or a fragment of a molecule for building:

  1. Activate the Add editor Add editor or the Select editor Selection editor.
  2. Select (in the Document view or in the Viewport using the Select editor) a fragment that you would like to use.
  3. Right-click on it and in the context menu to choose "Use selection to build":

Use selection to build

This should create a building fragment from the current selection.

If you want to modify the substitution atom, press Ctrl/Cmd and choose the substitution atom in the fragment as shown in the gif below.

Use selection to build

Note

In case of acceptable operations the fragment has a green overlay, while forbidden ones have a red overlay. You can control in the Preferences whether you want to follow these recommendations or override them (option: Prevent unexpected substitutions).

Building with available assets#

SAMSON provides a set of various assets by default. You can find all the available assets in the Asset Browser (Ctrl/Cmd + 4, Interface > Assets).

To search for available assets, use the "Filter assets..." at the top of the Asset Browser.

To change the size of images and text in the Asset Browser, you can zoom in / zoom out using Ctrl + mouse wheel or use commands with the magnifying glass with "+" and "-" icons.

To switch between the grid and the list view, use the right-most buttons (list mode, grid mode) at the bottom of the Asset Browser.

For the sake of tutorial, let's combine phenol molecules.

Open the Asset Browser (1), go to the Aromatics folder, and double-click on the phenol asset. This should activate the Add editor if it has not been active.

  1. Interface > Assets, , : Ctrl+4, : Cmd+4

Note

If you have the Add editor Add editor set as the active editor then you should see the chosen fragment shown right away in the center of the Viewport. If the Add editor is not the active editor, then simply double-click on the asset to activate the Add editor with this asset set as the current fragment.

First, we need to add the phenol molecule - click anywhere in the viewport. Then try adding phenol fragments to it using bond connections or by substituting atoms.

Note

You can change the substitution atom (or bond) in the fragment by holding the Ctrl/Cmd key and choosing the atom or bond in the fragment.

Building with phenol asset

Note

You can always apply interactive minimization (as done at the end in the example above) by pressing Z (or via Edit > Minimize). To stop the interactive minimization, press Z once again.

Let's now try to construct Bisphenol A (BPA) as follows (see the gif below):

  1. Use carbon atom to construct a propane molecule (C3H8).
  2. Change the current fragment to phenol. For that, in the Asset Browser, go to the Aromatics folder and click on the phenol asset (you should see the a#ctive fragment in the Viewport).
  3. Change the substitution atom in the phenol fragment. For that, press the Ctrl/Cmd key and choose the carbon atom as shown in the gif below.
  4. Substitute 2 hydrogens of the central carbon atom in the propane molecule by phenol fragments. For that, move your mouse to position the fragment onto hydrogen atoms of the central carbon atom in propane. You should see how the fragment is being automatically reoriented. Press the left -click to substitute an atom with the substitution atom of the current fragment.
  5. Apply interactive minimization by pressing Z (or via Edit > Minimize). To stop the interactive minimization, press Z once again.

Building Bisphenol A

Note

You can always rotate the fragment by holding Shift + right-click.

If you would like to see atom names when hovering above them as in the gif above, switch on the Node details Toggle node information option in the menu at the bottom of the Viewport.

You can also add labels to atoms, molecules, and other nodes, using the Label editor (Ctrl/Cmd + L) or via the context toolbar. Please refer to the Labeling tutorial for more information.

Orienting molecule fragments#

If you would like to change the orientation of the added fragment you can easily do it using Move editors. If you have just added a fragment to a molecule then it will be selected automatically, else you can select a part of a molecule in the Document view or in the Viewport.

Note

Multiple different Move editors are available in SAMSON. You can check them in the left-side menu in the Viewport, and you can learn more about their differences in the Moving objects section.

Click M to activate the local move editor. You can change the pivot for the rotation. For that zoom in such that the atom that you would like to set as the pivot is not hidden by the Move editor's controls as shown in the gif below, and click on the atom to set it as the pivot as shown in the gif below. Now you can use the move editor's controls to rotate the chosen fragment - press and hold anywhere on the controller's sphere and move the mouse to rotate using the trackball sphere. You can also use the arrow controllers to rotate around principal axis of the fragment.

You can learn more on how to move fragments of molecules and whole molecules please in the Moving objects section and in the Move objects in the Viewport interactive tutorial (1) in SAMSON.

  1. Help > Tutorials

Orienting a fragment of a molecule

Modifying hierarchical structure#

After you have built a molecule you might want to modify the hierarchical structure of the molecule or the document. You can do it easily in the Document view.

SAMSON provides you with the possibility to perform various changes of the document hierarchy:

  • add new nodes (structural model, chain, molecule, segment, structural group, etc),
  • move nodes using drag-and-drop,
  • extract nodes.

You can also modify node's properties using the Inspector (see Inspecting for more information).

To add a new node to some parent node, right-click on the parent node in the Document view and, in the context menu, go to Add > Structural node and choose a node by its type.

Adding a new structural node

To move nodes using the drag-and-drop mechanism, select nodes and drag them to a node where you would like to place them. SAMSON will automatically checks the validity of the drag-and-drop operation based on the node hierarchy.

To extract nodes, right-click on them and choose Extract structure from the context menu.

See also the "Documents: drag-and-drop, history" interactive tutorial (1) in SAMSON.

  1. Help > Tutorials