Building a molecule from fragments can feel deceptively simple: choose a piece, place it, and connect it. The difficult part is knowing whether the connection makes sense. A fragment may overlap the existing structure, attach through the wrong atom, or leave hydrogens and valences needing attention. A more reliable approach is to prepare the builder, choose the connection deliberately, and use the visual feedback to catch problems as you go.
In SAMSON, the Add editor is the main tool for adding atoms and molecular assets. Assets can be atoms, rings, functional groups, fragments, or whole molecules. The Asset Browser gives access to the built-in collection and assets available through SAMSON Connect. You can browse folders or search with Filter assets…; the grid and list buttons at the bottom switch how assets are displayed.
Set up the builder before connecting fragments
Before building, check Interface > Preferences > Editors > Add. For a typical fragment-building workflow, the documentation recommends enabling Adjust hydrogens when adding fragments…. With this option checked, SAMSON adjusts hydrogens, as best as possible, when adding or linking atoms and fragments, changing bond order, or changing formal charge.
Other options help address common placement and connection problems:
- Automatically orient fragments on substitution asks SAMSON to position a fragment, as best as possible, to avoid overlap with the existing molecule.
- Merge neighboring atoms merges fragment atoms that are close enough to atoms in the molecule, along with the substitution atom.
- Prevent unexpected substitutions displays acceptable operations with a green overlay and forbidden ones with a red overlay.
- Select fragments after adding them selects each newly placed fragment, making it easier to move or inspect.
- Randomize orientations randomizes the orientation of separately placed fragments, such as water or methane.
- Create new structural models when adding non-covalent fragments creates a separate structural model for each added fragment that is not covalently linked to another molecule in the document.
The overlay is guidance, not a substitute for checking the resulting structure. If you want to override the substitution recommendations, that behavior is controlled by the preference. For a careful first pass, leave Prevent unexpected substitutions enabled and treat a red overlay as a reason to pause and reassess the attachment.
Choose the connection, not just the fragment
When you select an asset, it becomes the current building fragment. In the Asset Browser, double-clicking an asset activates the Add editor with that fragment. Before placing it, check which atom in the fragment will form the connection. You can change the substitution atom by holding Ctrl on Windows or Linux, or Cmd on macOS, and choosing a different atom in the fragment. When using an asset to replace atoms and bonds in the document, holding Shift lets you choose which atom and bond in the asset are used for that replacement.
There are two useful ways to connect a fragment to an existing structure:
- Substitute an atom: hover over the atom you want to replace and click it. SAMSON positions the new atom or fragment while taking covalent radii into account.
- Create a bond: press and hold on the atom you want to connect to, move the cursor away, then release at a bond-like distance.
These actions serve different purposes. Substitution replaces the selected atom with the fragment’s connection atom; creating a bond attaches the fragment to the chosen atom. If the fragment appears to connect through the wrong site, change its substitution atom before placing it rather than trying to correct the connection afterward.
Use visual feedback, then review the result
As you position a fragment, SAMSON can predict its orientation and show whether a proposed operation is acceptable according to the substitution checks. With the relevant preferences enabled, it can also adjust hydrogens and merge nearby atoms. These features help make the assembly process easier to inspect, but the documentation describes orientation and hydrogen adjustment as best-effort. Review the resulting connectivity and geometry rather than assuming every placement is chemically correct.
For a larger example, the documented Bisphenol A workflow starts by building a propane molecule, then selecting phenol as the current fragment. The substitution atom is changed to the appropriate carbon, and two hydrogens on propane’s central carbon are replaced with phenol fragments. The automatic reorientation helps position each phenol during substitution; interactive minimization can then be applied with Z or Edit > Minimize. Press Z again to stop interactive minimization.
If you need to reposition a fragment after adding it, use a Move editor. The Local Move Editor is activated with M; clicking a bond lets it select the shortest fragment around that bond for movement. If the placement needs to be undone, use Edit > Undo, then adjust the fragment or connection and try again. This is often a cleaner fix than continuing to build on top of a connection you already know is wrong.
A useful routine is: set the Add editor preferences, select the asset, verify its substitution atom, inspect the overlay as you position it, and review the assembled structure before continuing. That small pause at each connection can save time later, especially when several fragments are involved.
For the complete workflow and additional examples, see the SAMSON guide to building molecules.
Note: SAMSON and all SAMSON Extensions are free for non-commercial use. Get SAMSON.