Molecular builder

In this tutorial, you will learn how to use the Molecular Builder tool, which makes it easy
to build complex molecular structures by combining atoms and molecular fragments.
As examples of use, you will build the ethanol and caffeine molecules.


The Molecular builder tool is selected using the molecular_builder_icon icon in the top plugins bar. You need to highlight a Stash configuration before activating the tool.

Ethanol molecule

Create a new empty project called “molecular_builder” and open the Builder builder_icon to get started:

  1. Use Add ‣ New Configuration to create a Stash item, and remove the hydrogen atom to create an empty configuartion.

  2. Activate the Molecular builder by clicking molecular_builder_icon. It will look like illustrated below.




What you see is a library of elements and fragments that can be added to the current Stash configuration. The most recently used ones appear at the top of the list.

Click Other and a periodic table will open up. You can now select the atomic elements you need to build your molecular structure. An easy way to build ethanol is to first build ethane, and then add the hydroxyl group:

  1. Click the C atom and select “SP3” to select a C atom that should be sp3 bonded.

  2. Click the 3D View to add the sp3 saturated carbon to the configuration. Note that this produces the methane molecule.

  3. Then click on one of its hydrogen atoms to substitute that atom for another sp3 bonded carbon. You have then built ethane.


Next, add the hydroxyl group:

  1. Select from the periodic table a sp3 O atom and make sure that the “Use VSEPR rules” option is selected. With this option we make sure that we are adding a OH group to the molecule (see more details about the “Use VSEPR rules” option below).

  2. Click one of the hydrogen atoms in the 3D View to substitute it for the OH group.


You have just built the ethanol molecule by combining atoms. You could also have built the same molecular structure by combining molecular fragments in a variety of ways. For instance, you could have added “Methanol” from the fragment library and then replaced one of its hydrogen atoms with the “Methane” fragment. Another easy alternative could be to select “Acetamide” fragment, remove its amine group and passivate the molecule to create sp3 O and C atoms:

  1. Import “Acetamide” fragment from the fragment library.
  1. Select the amine moiety and remove it.
  1. Go to Coordinate Tools ‣ Custom Passivator and choose “Hybridization 4(SP3)”.
  2. Tick “Use VSEPR rules” to ensure that you passivate the structure following the Valence Shell Electron Pair Repulsion (VSEPR) rules, and click “Passivate”.

The VSEPR rule determines the bonding coordination of an atom considering the minimum repulsion between its valence electron pairs (both shared and unshared). The use of VSEPR rules ensures the passivation of the structure considering the bonding electrons and the lone pairs. Instead, if we passivate the molecule without following the VSEPR rules each atom of the molecule will be passivated with the maximum number of hydrogen atoms for the corresponding hybridisation, as the lone pairs will no be considered.

In the latter case, we get the structure shown below if we passivate the molecule without considering the VSEPR rules.



It is always a safe choice to passivate the structure considering the VSEPR rules when building neutral molecules.


It is not possible to select any of the atoms in the 3D View while the Molecular builder window is active. You need to close this window first before the other Builder functionalities can be used.

Caffeine molecule

It is quite easy to use the Molecular builder to build complex structures from simple fragments instead of from atoms. You will now build the caffeine molecule, also known as 1,3,7-Trimethylpurine-2,6-dione. The chemical formula is C8H10N4O2.

  1. Add an empty configuration to the Stash and activate the Molecular builder molecular_builder_icon.

  2. Go to Fragments ‣ Simple rings and select “Benzene”.

  3. Click the 3D View to add benzene to the configuration.


  4. Select “Furane” from the Molecular Builder fragments library, and use mouse-click to select the hydrogen atom indicated below.


  5. In the 3D View, add the furane fragment to the configuration by clicking one of the hydrogen atoms. Note that the furane is fused to the benzene ring exactly at the hydrogen that was selected in the Molecular builder.


  6. Select the hydrogen atoms that are highlighted below and remove them.


In order to make sure that both rings are in the same plane, you need to do a dihedral rotation using the Z-matrix plugin:

  1. First select the atoms that define the dihedral angle. Once the angle is defined, you need to select the atoms that will move with the rotation; select the remaining atoms of furane moiety.



  2. Go to Coordinate Tools ‣ Z-matrix and the Z-matrix window will open up.

  3. Set the value of the angle you want to change as shown in the next figure.


Next, you need to overlap the C atoms that link both rings and remove the overlapping atom by “fusing” the rings:

  1. Select the atoms that will move; the atoms belonging to the furane moiety.

  2. Select the Move tool Move02_icon and select just the atom of furane linked to benzene moiety.


  3. Drag the selected atom so that it ends up on the top of the C atom of bencene linked to it and select the C atom numbered “1” in the below figure.


  4. Drag the C atom numbered “1” so that it ends up on the top of the nearest C atom of benzene as shown in the figure below.


  5. Click “Fuse” to remove the overlapping atoms.

  6. Close the Move window and click the 3D background to deselect the atoms.


  7. Go to Molecular Builder and slect sp2 N atom.

  8. Replace the C atoms by N as shown in the next figure.


  9. Follow the same steps to replace the H atoms by sp2 O atoms and “Methane” fragments and the oxygen atom belonging to the five-membered ring by a sp2 C atom, as shown in the next figure.


You have built the caffeine molecule! You could also have built it using “Indole” fragment and making the appropiate changes in the six- and five-membered rings.

Going further

In this tutorial you have built molecular structures starting from an empty configuration. You can also build a new structure starting from a molecular configuration that you already have or from a configuration imported from the Database, using Add ‣ from Database. You can add as many structures as you want to the Stash. In order to include them in your active configuration, you just need to drag and drop them onto the 3D View.

The next two structures are easily built using the steps outlined above. The first one can be built combining benzene and porphine fragments. For the second, you need to import C60 from the Database and then combine it with benzene, porphine, methane and formaldehyde fragments.




In order to link a new fragment to a fullerene molecule you will need to change the hybridisation of the carbon atom that will link to the new fragment.


You can click the “Help” button in the Move window to get more details about the Move tool.

Export the Stash Configuration file

Once you have built your molecular structure, you can save it in different formats. You just need to go to File ‣ Export Configuration as is shown in the next figure.


Please, note that it is also possible to export your configuration to a OpenBabel supported formats.