A molecular structure can look complete and still be difficult to parameterize. A ligand may be unsupported by the protein’s force field, hydrogens or terminal residues may be missing, or an atom-selection rule may include the wrong part of the system. The frustrating part is that these issues can surface before you ever reach energy evaluation.
A useful way to troubleshoot is to treat force-field setup as a sequence of decisions: identify what kinds of atoms are in your target, choose a workflow that matches them, and check the setup diagnostics before creating the interaction model. Here is a practical route through that process in SAMSON.
Start with the system, not the force-field menu
First, ask whether your target is a single kind of system or a combination of components. A protein, nucleic acid, water-and-ion system, or small organic molecule can usually start in Standard mode. Typical biomolecular choices include Amber or CHARMM presets; Sage or Parsley are options for small organic molecules.
A protein–ligand complex often needs a different arrangement: the protein uses Amber or CHARMM, while the ligand uses an OpenFF force field such as Sage or Parsley. That is the use case for Composite mode. Choose Advanced when different atom groups need separate force-field files, or when you need to work directly with official or custom XML or OFFXML files.
This distinction is more than a menu preference. It helps you avoid trying to force a single parameter set onto atoms that require different treatment.
Prepare before you diagnose typing failures
For Amber or CHARMM protein and nucleic-acid workflows, inspect the structure before selecting a preset. Resolve alternate locations so they are not imported together, decide on protonation states before adding hydrogens, and check that termini are complete or capped. Unsupported ligands, cofactors, additives, and buffer molecules can also prevent typing when they are included in a setup that does not parameterize them.
Pay attention to waters, ions, and connectivity too. Choose a compatible water-and-ion model when the option is available, and look for accidental covalent bonds between otherwise separate components. In Composite mode, do not remove a ligand that you intend to parameterize separately.
For a protein–ligand system, verify the selection
Composite mode depends on assigning ligand atoms to the NSL class lig. After choosing the protein and ligand force fields, press Refresh ligand query and inspect the Ligand class row. The query n.c lig should select the expected ligand atoms—neither zero atoms nor every atom in the document.
There must also be at least one protein atom outside the ligand selection. Composite mode does not support covalent bonds between protein and ligand atoms, so a covalently attached ligand needs a force field that represents that covalent chemistry directly. These checks are worth doing before interpreting any setup status: a selection that is too broad or too narrow can make the intended assignment impossible.
Use validation as a diagnostic, not a formality
Wait for the setup window to report whether the force field is ready for the current target. If it reports warnings, read them before proceeding. Warnings may be acceptable for exploration, but they should be understood before relying on results.
In Advanced mode, group order matters: earlier explicit groups take priority, and the default * group handles atoms left over. Check that each explicit NSL query selects the intended atoms. An empty group, an overly broad query, or atoms already assigned by a higher-priority group can produce useful diagnostics. Also keep XML and OFFXML files in separate groups; files within one group must come from the same provider family.
If only some atoms are problematic, SAMSON may offer Exclude. Use that option only when removing those atoms from the simulator target is scientifically appropriate—not simply to make the warning disappear.
Check what was actually created
After setup, inspect the Molecular Mechanics Force Fields properties. Confirm the provider and parameter set, and review constraints, energy, and generated terms. The Types and Atoms details show atom typing and per-atom parameters; Warnings and Status provide additional context. If the first energy evaluation is still running, wait for it to finish before interpreting the energy or forces.
A reliable workflow is simple: prepare the structure, choose Standard, Composite, or Advanced based on its components, validate the target, and read the warnings before interpreting results. For the complete setup instructions, see the SAMSON molecular mechanics force-field tutorial.
Note: SAMSON and all SAMSON Extensions are free for non-commercial use. Get SAMSON.