A force-field setup can fail for a frustrating reason: the structure may look complete, but one atom, residue, or group does not match the parameters you selected. The useful first step is not to try presets at random. It is to work out which parts of the system need parameters, then check whether your setup is designed to cover them.
This workflow helps you distinguish common issues—such as an unsupported ligand, an incorrect atom selection, or a mixed file setup—before you create a simulation. It applies to the Molecular Mechanics Force Fields interaction model in SAMSON.
Start with the system, not the preset
Choose a setup based on what is in your document:
- Standard: a system that can use one force-field setup, such as a protein, nucleic acid, water and ions, or a small organic molecule. Typical choices include Amber or CHARMM for biomolecules and Sage or Parsley for small molecules.
- Composite: a protein–ligand system where the protein uses Amber or CHARMM and the ligand uses an OpenFF force field such as Sage or Parsley.
- Advanced: a system that needs different force-field files for different atom groups, or a custom force-field workflow.
This distinction matters because a force field that is appropriate for one part of a structure may not parameterize everything else. For example, an Amber- or CHARMM-only setup may report problems if the document also contains a ligand or cofactor that those selected files do not cover.
Check the structure before changing settings
For Amber or CHARMM typing of proteins and nucleic acids, inspect the target structure first. Resolve alternate locations so they are not all imported together, decide protonation states before adding hydrogens, and check that termini and fragments are complete or intentionally capped. Also review heterogens, waters, ions, and any accidental covalent bonds between components.
These checks are more useful than treating every warning as a force-field problem. A setup may be unable to type atoms because the input structure includes unsupported components, not because the selected preset is inherently wrong. If a component should not be part of the simulation target, consider whether excluding it is scientifically appropriate before using the setup window’s Exclude option.
For protein–ligand systems, verify the selection
Composite mode depends on the ligand selection being precise. Assign the ligand atoms to the NSL class lig, select a protein preset and ligand force field, then press Refresh ligand query. Check that the ligand row reports the expected atom count for n.c lig.
If the query selects no atoms, or selects every atom in the document, the composite setup cannot be created. Composite mode also requires 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, choose a force-field approach that represents that chemistry directly rather than trying to treat the two parts as a noncovalent composite.
Use Advanced groups deliberately
In Advanced mode, each group pairs an NSL query with force-field files. Explicit groups are evaluated in the displayed order, and earlier groups take priority. The default * group comes last and handles atoms not matched by earlier groups.
When an explicit group matches no atoms—or its atoms have already been assigned to an earlier group—the diagnostics can help explain why the intended files are not being used. Check each query against the atoms you mean to parameterize. Also keep provider families separate within a group: XML and OFFXML files cannot be mixed in the same group. If different parts of the system need those formats, put them in separate groups.
A practical troubleshooting sequence
- Confirm that the target atoms are loaded in the active document and that the intended selection is active.
- Prepare biomolecular structures and review unsupported or unintended components.
- Choose Standard, Composite, or Advanced according to how many parameter sets the system needs.
- For Composite, verify the ligand query and its atom count. For Advanced, inspect group queries, order, and file families.
- Wait for setup validation and read the status and warnings before pressing OK.
- After creating the model, inspect the provider, parameter set, constraints, energy, generated terms, atom types, per-atom parameters, warnings, and status.
A ready status confirms that the current setup can be used for the target; it is not a substitute for understanding warnings or evaluating whether the structure and model are appropriate for your scientific question. For routine interactive work, the documentation recommends Constrained; use Unconstrained when X–H bond flexibility needs to be preserved.
Read the Molecular Mechanics Force Fields tutorial for the complete setup steps and details.
Note: SAMSON and all SAMSON Extensions are free for non-commercial use. Get SAMSON.