A force-field setup can fail for reasons that have little to do with the force field itself. A structure may contain alternate locations, missing hydrogens, unsupported heterogens, or atoms assigned to the wrong group. And even when setup succeeds, warnings can be easy to overlook. The useful habit is to treat parameterization as a validation step—not just a menu choice—before interpreting energies or forces.
Here’s a practical way to narrow down the problem in SAMSON, starting with the most important question: which parts of your system need which parameters?
Choose the setup by system, not by familiarity
For a single biomolecular system—such as a protein, DNA, RNA, water, or ions—start with Standard and a suitable Amber or CHARMM preset. For a small organic molecule, Standard with Sage or Parsley is a typical choice. For a protein–ligand complex where the ligand needs OpenFF parameters, use Composite: assign the protein and ligand to their respective force fields. Choose Advanced when you need to control force-field files or assign different files to specific atom groups.
This distinction helps avoid a common source of confusion: one setup workflow is not automatically suitable for every component in a mixed system. If you are unsure, first identify the protein, ligand, waters, ions, and any other components that need parameterization, then choose the workflow that can represent those groups.
Check the structure before changing force fields
For Amber or CHARMM typing, inspect the structure itself before troubleshooting presets. Common issues include alternate locations imported together, missing hydrogens, uncertain protonation states, incomplete termini or fragments, unsupported ligands or cofactors, and waters or ions without a compatible model. Accidental covalent bonds between otherwise separate components can also interfere with setup.
In practice, this gives you a sensible order of operations: clean up the target, choose the force-field workflow, and then check the setup status. Changing force fields before checking the structure may not address the underlying cause.
Use the status as a diagnostic, not a green light
The setup window checks whether the selected force field can parameterize the current target. Wait for the status message before creating the interaction model. If it reports that the force field is ready, you can continue; if it reports warnings, read them and decide whether they are acceptable for your purpose. A successful setup does not make warnings irrelevant.
If only some atoms are problematic, SAMSON may offer Exclude. Use it only when removing those atoms from the simulator target is scientifically appropriate. Excluding atoms simply to make setup proceed can change what the model represents.
For protein–ligand systems, verify the selection
Composite mode depends on the ligand being selected correctly. Assign ligand atoms to the NSL class lig, refresh the ligand query, and check that the reported atom count matches the intended ligand. The query n.c lig must select only ligand atoms—not zero atoms and not the entire document. Composite mode also requires at least one protein atom outside the ligand selection and does not support covalent bonds between protein and ligand atoms.
That atom-count check is a small step with a large practical benefit: it lets you catch a selection mistake before trying to interpret a failed parameterization.
For Advanced mode, make group assignments unambiguous
Advanced groups are evaluated in order, and earlier explicit groups take priority. The default * group comes last and handles atoms not matched earlier. Check that each explicit NSL query selects the intended atoms; diagnostics may indicate that a group matches no atoms or that its atoms were already assigned by a higher-priority group.
Also keep provider families separate within a group: XML and OFFXML files cannot be combined in the same group. If one part of the system needs XML files and another needs OFFXML files, place them in separate groups.
Only interpret results after checking them
Once the interaction model is created, start the simulation and wait for the first energy and force evaluation. In the properties window, review the provider and parameter set, constraints, energy, generated terms, atom types, per-atom parameters, warnings, and status. These checks help establish what was actually assigned and whether evaluation is active before you draw conclusions from the result.
A reliable sequence: prepare the structure, choose Standard, Composite, or Advanced based on the system, validate the target, read warnings, and inspect the created model. For routine interactive work, the documentation recommends the constrained model; use unconstrained mode when X–H bond flexibility needs to be preserved.
For the complete workflow and setup details, read the Molecular Mechanics Force Fields tutorial.
Note: SAMSON and all SAMSON Extensions are free for non-commercial use. Get SAMSON.