A protein–ligand structure can look perfectly reasonable in a molecular viewer and still fail when you try to assign a force field. The protein may be recognized, but the ligand may be unsupported by the selected parameters—or the selection intended to identify the ligand may accidentally include the whole document. These are different problems, and separating them makes setup much easier to troubleshoot.
In SAMSON, a useful approach for a protein that uses Amber or CHARMM parameters and a ligand that needs OpenFF parameters is Composite setup. The key idea is to treat the protein and ligand as separate parameterization targets, then check that each target is being identified as intended before creating the interaction model.
First, decide whether Composite is appropriate
Composite setup is intended for a protein–ligand system in which the protein uses an Amber or CHARMM preset and the ligand uses Sage or Parsley. It is not a general fix for every molecule that causes a typing error. In particular, Composite mode does not support covalent bonds between protein and ligand atoms. If the ligand is covalently attached, choose a force-field approach that represents that covalent chemistry directly.
Before opening the setup window, prepare the structure. For Amber or CHARMM typing, common sources of trouble include multiple alternate locations imported together, missing hydrogens, uncertain protonation states, incomplete termini, unsupported heterogens, and accidental bonds between different components. Decide which atoms belong in the simulation and address these issues before interpreting a setup failure as a force-field problem.
Make the ligand selection testable
Composite mode identifies ligand atoms using the Node Specification Language query n.c lig. Assign the ligand atoms to the lig class, then use Refresh ligand query in the Composite tab. The resulting Ligand class row reports how many atoms match the query.
That count is a small but important diagnostic. Before proceeding, ask:
- Does the query match the ligand atoms you meant to select?
- Does it match a nonzero number of atoms?
- Does it avoid selecting every atom in the document?
If the count is zero, the ligand has not been identified by the query. If it includes the entire document, the selection is too broad. In either case, fix the class assignment or query result before trying to create the model. Composite setup also requires at least one protein atom outside the ligand selection.
Use the setup status as a checkpoint
Once the ligand selection is correct, choose a protein preset and a ligand force field, then wait for the setup status. The setup window checks whether the selected force field can parameterize the current target, and OK is enabled only when the setup can be used.
If setup is not ready, read the reported status rather than repeatedly changing presets. A message about the ligand query points toward selection; a message about unsupported atoms points toward structure preparation or parameter coverage. Warnings should also be reviewed before relying on results. They may not always prevent exploratory work, but their meaning should be understood before interpreting energies or forces.
After creation, verify what was built
Creating the interaction model is not the end of the check. In the Molecular Mechanics Force Fields properties window, confirm the Provider and Parameter set. Inspect Details > Types for atom typing and Details > Atoms for per-atom parameters. Review Warnings and Status, and check that energy and generated terms are available after the first evaluation.
This sequence turns a vague “force-field setup failed” problem into a set of specific questions: Is the structure prepared? Is the ligand selection correct? Is the chosen setup suitable for the chemistry? Does the resulting model contain the expected types and parameters? Checking these in order helps avoid treating a selection mistake as a parameterization failure—or trusting a model before inspecting its warnings.
For the complete SAMSON workflow, see the Molecular Mechanics Force Fields tutorial.
Note: SAMSON and all SAMSON Extensions are free for non-commercial use. Get SAMSON.
