Building molecules

In this section, you will learn how to build molecules in SAMSON using atoms and fragments (assets). We will go from constructing a simple fragment from atoms to constructing a molecule from several assets.

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

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 Edit menu or Quick access commands...

Building with atoms

or using the Periodic table...

Building with atoms from Periodic Table

or you can build by assembling assets

Building with assets

Assets can be anything: atoms, functional groups, rings, fragments, radicals, whole molecules, proteins, nanoparticles, 2D materials, etc.

Just assemble them in the document to rapidly set up complex models for analysis and simulation.

The builder has several cool features to assist you: as shown above, in particular, it has options to predict fragments orientations and prevent implausible substitutions: acceptable substitutions or additions have a green overlay, while forbidden ones have a red overlay (you control in the Preferences whether you want to follow these recommendations or override them).

Whether you’re constructing with individual atoms or with assets, the builder can also adjust hydrogens for you, and merge overlapping atoms.

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

SAMSON has the Asset Browser ( Ctrl/ Cmd⌘ + 4, Interface menu > Assets), which gathers the assets included by default in SAMSON together with the assets you can obtain from SAMSON Connect:

Asset browser

Try going through various folders in the Asset Browser to see what is available. To search for available assets, use the "<i>Search assets...</i>" on the top of the Asset Browser.

Asset browser

We will be adding more and more assets in the default ones and making available more assets in SAMSON Connect - Extensions. If you would like to make your library of fragments/molecules available in SAMSON, contact us.


Before going through this section, we recommend going through the interactive tutorials integrated into SAMSON (Help menu > Tutorials) that will guide you through the basic operations. Specifically, we recommend going through the following interactive tutorials:

  • Working with documents
  • Selecting in the Viewport
  • Building with atoms
  • Moving objects in the Viewport

Interactive tutorials in SAMSON

You can also check the section of the User Guide on Selecting, Moving around, Moving objects.

In this section, we will partly cover what is covered in the aforementioned interactive tutorials as well.


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

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

Add editor preferences

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 N-Acetyl group

Building N-Acetyl group

Let’s start by constructing a simple N-acetyl group. The building in SAMSON is done thanks to the Add editor (shortcut: A, Home menu > Edit > Add or Edit menu > Edit> Add).

With the Add editor, you can build with atoms and available fragments.

Switch to the Edit menu and click on the Add editor.

Edit menu

Note: You can see the Snapping options in the Edit menu – they might influence how the fragments are added and positioned. Just set both of them to Off for the sake of this tutorial. Snapping can be useful, for example, when you need to place fragments on a grid with a specific distance between them.

This should active the Add editor and you should see the current active fragment in the Viewport, and it will also open the Asset Browser with all the available assets.

You also have quick access to some common atoms, rings, the Periodic Table with all atoms, and the Asset Browser in the Add section of the Edit menu and in the Quick access widget in the top-right part of the viewport.

Let’s start by adding a Carbon atom: click on C (Carbon) in the Edit menu and click anywhere in the Viewport.

Add carbon atom

With the "Adjust hydrogens..." option checked 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.

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

Note: In case of acceptable operations the fragment will have 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).

Use one of these modes to add another Carbon.

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

When building you can always switch on the interactive minimization in SAMSON (shortcut: Z, Home menu > 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

Note: If you need to use other atom types, click on the Periodic table ( Ctrl/ Cmd⌘ + 5, Edit menu > Add > Periodic table) and choose an atom from there simply by clicking on it.

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 editor (shortcut: B, Edit menu > Edit > Edit bonds). Click on this 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. Please note, that depending on the file format in which you will be saving it might be saved as a single bond. Check the next paragraph on how to modify the bond order using the Inspector.

You can also modify the bond order by selecting the bond and going to the Inspector ( Ctrl/ Cmd⌘ + 2, Interface menu > Inspector) to change the bond order and bond type. But in this case, hydrogens will not be adjusted automatically.

Inspect bond order

Changing atom formal charge

If you want to modify formal charges of atoms, you can use the Edit charges editor (shortcut: C, Edit menu > Edit > Edit charges). Click on the 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. For that, select (in the Document view or in the Viewport using the Select editor) a fragment that you would like to use, activate the Add editor (shortcut: A) and 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 Shift and choose the substitution atom in the fragment as shown in the gif below.

Use selection to build

Building with available assets

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

To search for available assets, use the "Search assets..." on 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.

You can also switch between the grid and the list view using the right-most buttons at the bottom of the Asset Browser.

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

Open the Asset Browser ( Ctrl/ Cmd⌘ + 4, Interface menu > Assets), go to the Aromatics folder, and double-click on the phenol asset. This should activate the Add editor if it has not been active.

Note: If you have the 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 currently 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. You can also change the substitution atom (or bond) in the fragment by holding the Shift 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. To stop the interactive minimization, press Z once again.

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

  • Use carbon atom to construct a propane molecule (C3H8).
  • 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 active fragment in the Viewport).
  • Change the substitution atom in the phenol fragment. For that, press the Shift key and choose the carbon atom as shown in the gif below.
  • 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 mouse button to substitute an atom with the substitution atom of the current fragment.

Building Bisphenol A

Note: You can always rotate the fragment by holding Shift + right mouse button.

Note: If you would like to see atom names when hovering above them as in the gif above, switch on the Node details option in Interface menu > Node details (or in the menu at the bottom of the Viewport).

Note: You can also add labels to atoms, molecules, and other nodes, using the Label editor ( Ctrl/ Cmd⌘ + L, Home menu > Edit > Label) or by right-clicking on a node and choosing from the context menu "<i>Label clicked node</i>" or "<i>Label clicked...</i>". Please note, that labeling depends on the current Selection filter which you can change in the top-left part of the Viewport.

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 Home menu > Edit > Move or in Edit menu > Move, and you can learn more about their differences in the Moving objects section.

Click M to activate the Move editors. 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, hold the Shift key and set the atom as the pivot. 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.

Orienting a fragment of a molecule

Learn more on how to move fragments of molecules and whole molecules in the Moving objects section and in the Move objects in the Viewport interactive tutorial in SAMSON (Help menu > Tutorials).

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 by selecting the node.

To add a new node to some parent node, right-click on the parent node and go to Add > Structural node in the context menu 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.