Web Analytics Made Easy - Statcounter
Skip to content

Molecular Mechanics Force Fields#

Use this tutorial when you want to compute energies and forces with an Amber, CHARMM, or OpenFF-style molecular mechanics force field in SAMSON.

You will create a Molecular Mechanics Force Fields interaction model, choose a force-field setup that matches your system, check that the selected force field can parameterize the target, then run or minimize the system interactively.

What you will learn#

In this tutorial, you will learn how to:

  • choose between Standard, Composite, and Advanced setup workflows
  • install or update the local Amber, CHARMM, OpenFF, and reference Python bundles
  • prepare biomolecular targets before Amber or CHARMM typing
  • assign different force fields to different atom groups with NSL queries
  • inspect assigned atom types, per-atom parameters, warnings, energy, generated terms, and setup status

Before you start#

Before creating a simulation in SAMSON, make sure that:

  • the Molecular Mechanics Force Fields extension is installed
  • the system you want to parameterize is loaded in the active document
  • the relevant atoms are selected if you want the simulator to target only part of the document

For Amber or CHARMM protein and nucleic-acid workflows, prepare the structure first: choose one alternate location, add hydrogens after deciding protonation states, complete or cap termini, and remove unsupported heterogens unless they are intentionally parameterized.

Choose the right setup#

Start from the system you have:

If your system is... Use this setup Typical choice
A protein, DNA, RNA, water, or ions Standard Amber 14, Amber 19, CHARMM 36, or CHARMM 36 2024
A small organic molecule Standard Sage or Parsley
A protein-ligand complex where the ligand needs OpenFF parameters Composite Amber or CHARMM for the protein, Sage or Parsley for the ligand
A system where different atom groups need different force-field files Advanced NSL groups, each with its own XML or OFFXML files
A custom or experimental force-field workflow Advanced Official or local .xml / .offxml files

Use Constrained for routine minimization and interactive use. Use Unconstrained only when X-H bond flexibility needs to be preserved.

Add the simulator#

  1. Open a document containing the molecular system you want to evaluate.
  2. Add a simulator via Edit > Simulate > Add simulator.
  3. Select Molecular Mechanics Force Fields as the interaction model.
  4. Choose the state updater you want to use, for example FIRE.
  5. Press OK.

The Molecular Mechanics Force Fields setup window appears.

Install local bundles#

If no force-field choices appear yet, use the small reload button at the top of the setup window.

This installs or updates the local Amber, CHARMM, OpenFF, and reference Python bundles used by the extension. The button tooltip tells you whether bundles will be installed or updated. During installation, the setup window shows a progress bar and a log area. When installation finishes, presets and official force-field files are refreshed automatically.

Note

You only need to install bundles when they are missing or when you want to update them.

Set up a biomolecule or small molecule#

Use Standard for most single-force-field systems.

  1. Open the Standard tab.
  2. Choose a Preset that matches your system.
  3. For Amber or CHARMM presets, choose the Water / Ions model when this option appears.
  4. Enable GLYCAM or Lipids only when your system needs those extra parameter files.
  5. Choose Constrained unless you specifically need an unconstrained model.
  6. Wait for the status message.

When the status says Force field is ready for the current target, press OK to create the interaction model.

If the status reports warnings, inspect them before continuing. Warnings may still be acceptable for exploration, but they should be understood before relying on the result.

Prepare a biomolecular target#

Use Prepare before Amber or CHARMM typing when the structure may need cleanup.

The preparation guidance in the setup window focuses on common causes of typing failures:

  • alternate locations imported together
  • missing hydrogens or uncertain protonation states
  • incomplete peptide or nucleic-acid fragments
  • unsupported ligands, cofactors, crystallographic additives, or buffer molecules
  • waters and ions without a compatible water / ion model
  • accidental covalent bonds between protein, nucleic acids, ligands, waters, or ions

In Composite mode, do not remove the ligand if it should be parameterized separately: ligand atoms must still match the n.c lig query.

Set up a protein-ligand composite#

Use Composite when a biomolecular protein should use Amber or CHARMM and a ligand should use Sage or Parsley.

  1. Assign the ligand atoms to the NSL class lig.
  2. Open the Composite tab.
  3. Choose a Protein preset.
  4. Choose a Ligand force field.
  5. Press Refresh ligand query.
  6. Check that the Ligand class row reports the expected number of atoms for n.c lig.
  7. Wait for the status message, then press OK when the setup is ready.

Warning

The n.c lig query must select only ligand atoms. If it selects no atoms, or every atom in the document, the composite setup cannot be created.

Composite mode needs at least one protein atom outside the ligand selection, and it does not support covalent bonds between protein and ligand atoms. If the ligand is covalently attached, use a force field that represents the covalent chemistry directly.

Use Advanced mode#

Use Advanced when you need direct control over force-field files or atom groups.

Advanced mode has a Groups list. Each group has:

  • an NSL query
  • a Selected files list
  • file actions: Add official..., Add custom..., Remove, Move up, and Move down

Explicit groups are evaluated in the order shown. Earlier explicit groups have priority. The default * group is always last and handles atoms not matched by earlier groups.

To assign files manually:

  1. Open the Advanced tab.
  2. Select the group you want to edit.
  3. For an explicit group, set the NSL query that selects the atoms in that group.
  4. Press Add official... to choose Amber, CHARMM, or SMIRNOFF files from the local catalogs.
  5. Press Add custom... to add local .xml or .offxml files.
  6. Use Move up and Move down if file order matters.
  7. Wait for the status message, then press OK when the setup is ready.

Use Add group when you need a separate force field for a subset of atoms. Use Remove to delete an explicit group. The default * group cannot be removed.

Warning

Files within one group must come from one provider family: XML or OFFXML. To use XML for one part of the system and OFFXML for another, create separate groups.

The status details may include Group diagnostics when an explicit group matches no atoms or when all of its atoms were already assigned by higher-priority groups.

Add official or custom files#

The Add official force-field files dialog lets you filter by:

  • Source: AMBER, CHARMM, or SMIRNOFF
  • Series
  • Category

Use Add selected to add the selected official files to the current group.

Use Add custom... for local .xml or .offxml files. Custom files are useful when testing a force field that is not part of the installed bundles.

Understand setup results#

The setup window checks the selected force field against the current target before creating the interaction model. OK is enabled only when the current setup can be used.

If setup fails, the status message usually tells you what to fix. Common causes include:

  • missing hydrogens or incomplete terminal residues in biomolecules
  • alternate locations imported together
  • unsupported ligands or cofactors in an Amber or CHARMM-only setup
  • a ligand query that selects the wrong atoms in Composite mode
  • an Advanced group with an empty or overly broad NSL query
  • XML and OFFXML files selected together in a single group
  • a custom force-field file that uses unsupported constructs

When only some atoms are problematic, the setup window may show Exclude. Use this only when it is scientifically appropriate to remove those atoms from the simulator target and retry the setup check.

Run the simulation#

After the interaction model is created:

  1. Press Edit > Simulate > Start.
  2. Wait for the first energy and force evaluation.
  3. Move atoms interactively or minimize the system with the chosen state updater.

If the energy is not ready yet, wait for the first evaluation to finish and inspect the status in the properties window.

Inspect the result#

Open the Molecular Mechanics Force Fields properties window to check what was created.

Review:

  • Provider and Parameter set to confirm which force field was used; hover over Parameter set when you need the resolved source path
  • Constraints to confirm constrained or unconstrained mode
  • Energy and Generated terms to confirm that evaluation is active
  • Details > Types to inspect atom typing
  • Details > Atoms to inspect per-atom force-field parameters
  • Details > Warnings and Details > Status before interpreting the result

For practical work, use this sequence:

  1. Prepare the molecular structure.
  2. Choose Standard for single-force-field systems, Composite for protein-ligand systems, and Advanced for group-specific or custom files.
  3. Use Constrained for routine interactive work.
  4. Wait for setup validation before creating the model.
  5. Read warnings before interpreting energies or forces.

Need Help?#

Have questions or feedback? Feel free to reach out via the Forum, via e-mail, via the Feedback button in SAMSON, or by directly discussing with us.

References#