A force-field setup can fail for a frustrating reason: the selected parameters may be suitable for one part of a structure but not another. A protein–ligand complex, for example, may need biomolecular parameters for the protein and a separate force field for the ligand. Before interpreting an energy or starting a minimization, it helps to match the setup to the system and check exactly which atoms it will cover.
This workflow is designed to catch common setup problems early in SAMSON. It is especially useful when a force field reports warnings, a ligand is not being parameterized as expected, or the setup window will not let you create the interaction model.
First, match the workflow to the system
Use Standard when one force-field setup can cover the target: for example, a protein, DNA, RNA, water, or ions with an Amber or CHARMM preset, or a small organic molecule with Sage or Parsley.
Choose Composite when a biomolecular component and a ligand need different force fields—for instance, Amber or CHARMM for the protein and Sage or Parsley for the ligand. Choose Advanced when you need to assign files to multiple atom groups or use custom XML or OFFXML files.
This choice prevents a common mismatch: trying to parameterize a mixed system as if every atom belonged to the same force-field workflow. If you are unsure, start with the simplest setup that fits the chemistry and target. Reserve Advanced mode for cases that need its group-by-group control.
Prepare the target before checking parameters
For Amber or CHARMM typing, structure preparation matters. Before creating the simulator, check whether alternate locations have been imported together, whether hydrogens are missing, and whether protonation states have been considered. Confirm that peptide or nucleic-acid fragments and termini are complete or appropriately capped. Also review ligands, cofactors, additives, buffer molecules, waters, and ions: unsupported components or incompatible water and ion choices can prevent a clean setup.
Look for accidental covalent bonds between components that should be separate. In Composite mode, however, do not remove a ligand that you intend to parameterize separately. Its atoms need to remain in the document so the ligand query can find them.
For a protein–ligand complex, verify the selection
Composite mode relies on the Node Specification Language (NSL) class lig to identify ligand atoms. Assign the ligand atoms to that class, select a protein preset and ligand force field, and press Refresh ligand query. Then inspect the Ligand class row and confirm that n.c lig selects the expected number of atoms.
This small check can save time: a query that selects no atoms cannot parameterize the ligand, while one that selects every atom does not distinguish the ligand from the rest of the system. Composite mode also needs at least one protein atom outside the ligand selection and does not support covalent bonds between protein and ligand atoms. If the ligand is covalently attached, use a force field that represents that covalent chemistry directly.
Use the status message as a diagnostic
Wait for setup validation before pressing OK. The setup window checks the selected force field against the current target, and the status message usually points to issues that need attention. Typical causes include missing hydrogens, incomplete terminal residues, unsupported ligands in a biomolecule-only setup, an empty or overly broad NSL query, or XML and OFFXML files placed in the same Advanced group.
In Advanced mode, explicit groups are evaluated in the order shown, and earlier groups take priority. The default * group handles atoms not matched by earlier groups. If an explicit group matches no atoms—or all its atoms have already been assigned—the diagnostics may help explain why. Keep XML and OFFXML files in separate groups; files within a single group must come from one provider family.
A setup marked ready means the selected configuration can be used for the current target. It does not remove the need to read warnings or assess whether the model is appropriate for your scientific question. After creating the interaction model, inspect its provider, parameter set, constraints, energy, generated terms, atom types, per-atom parameters, warnings, and status. If energy is not available immediately, wait for the first evaluation to finish.
A quick pre-run checklist
- Choose Standard, Composite, or Advanced based on the atoms and force fields needed.
- Prepare biomolecular structures and review unsupported components.
- In Composite mode, confirm that
n.c ligselects only the intended ligand atoms. - In Advanced mode, check group order, query matches, and file-family consistency.
- Read warnings before interpreting energies or forces.
For routine interactive use and minimization, the documentation recommends Constrained; use Unconstrained when X–H bond flexibility needs to be preserved.
Read the full Molecular Mechanics Force Fields tutorial for setup steps, details on local bundles, and additional troubleshooting guidance.
Note: SAMSON and all SAMSON Extensions are free for non-commercial use. Get SAMSON.