A familiar frustration in molecular modeling: you find the fragment you need, but attaching it to an existing structure can leave atoms overlapping, hydrogens out of place, or the new piece pointing in an awkward direction. A reliable workflow is to let the builder help with placement, check the proposed connection before committing, and refine the geometry as you go.
In SAMSON, the Add editor is the main tool for building with atoms and molecular fragments. It works with assets from the Asset Browser, as well as fragments you select from the current document. The steps below focus on the practical decisions that make fragment assembly easier to manage.
Start with the builder settings
Before adding anything, open Interface > Preferences, then go to Editors > Add. For a typical fragment-building workflow, check the options you want to use:
- Adjust hydrogens when adding fragments adjusts hydrogens, as best as possible, when adding or linking atoms and fragments, editing bond order, or changing formal charge.
- Automatically orient fragments on substitution helps position a fragment so its atoms do not overlap with atoms already in the molecule.
- Merge neighboring atoms merges fragment atoms that are close enough to atoms in the existing molecule.
- Prevent unexpected substitutions marks acceptable operations in green and forbidden ones in red.
These are recommendations, not a replacement for checking the structure. If you prefer to make a connection that the builder flags, you can control whether substitutions are prevented in Preferences.
Choose the attachment point deliberately
Activate the Add editor and choose a fragment in the Asset Browser. To find an asset, use Filter assets…; the browser also lets you switch between grid and list views. Double-clicking an asset activates it as the current building fragment if the Add editor was not already active.
When using a fragment you assembled yourself, select it in the Document view or Viewport, right-click, and choose Use selection to build. You can then change which atom in the fragment is used for substitution: hold Ctrl on Windows or Linux, or Cmd on macOS, and choose the desired atom.
For available assets, the current fragment appears in the Viewport. If you need to change the substitution atom or bond while building, the controls depend on the workflow: for a fragment made from a selection, use Ctrl/Cmd to choose the substitution atom; when selecting the asset atom or bond to replace, hold Shift as described in the builder overview.
Connect by substitution or by a bond
There are two useful ways to attach a new atom or fragment:
- Substitute an atom: position the fragment over the atom you want to replace and click. SAMSON attempts to place the new fragment using the covalent radii of the atoms. With automatic orientation enabled, it also attempts to orient the fragment to avoid overlap.
- Create a bond: press and hold on the atom you want to connect to, move the pointer away, and release at a bond-like distance.
These actions solve different modeling needs. Substitution replaces an existing atom with the chosen attachment point; bond creation adds a connection from the atom you start on. Check the preview and the resulting structure so the connection matches your intended chemistry.
The green and red overlays are useful feedback before you click: green indicates an acceptable operation, while red indicates one the builder considers forbidden. If a substitution is not landing where you expect, confirm that you selected the intended attachment atom and try changing the fragment orientation. You can rotate a fragment during placement with Shift + right-click.
Refine geometry as you build
Interactive minimization can run while you build. Press Z, or choose Edit > Minimize, to switch it on; press Z again to stop. This lets you see the system relax as connections are added, rather than waiting until the end. It is still worth checking the structure after building: minimization helps adjust geometry, but it does not decide whether the molecular design is what you intended.
If a fragment is attached correctly but needs a different orientation, select it and use a Move editor. The Local Move Editor, activated with M, can set a rotation pivot by clicking an atom; clicking a bond lets it select the shortest fragment for rotation around that bond. Use the Moving objects guide for details on the available move editors.
For a compact example, the documentation demonstrates assembling Bisphenol A by building a propane backbone, choosing phenol as the current fragment, selecting its attachment carbon, and substituting two hydrogens on the central carbon. The example brings together the key ideas: choose the right attachment point, allow the fragment to orient, then minimize and inspect the result.
Read the SAMSON guide to building molecules to explore atom-by-atom building, fragment assets, bond and charge editing, and document hierarchy tools.
Note: SAMSON and all SAMSON Extensions are free for non-commercial use. Get SAMSON.