Force Fields¶

MolPy’s force‑field layer connects structural data (Frames/Atomistics) to simulation parameters (atom types, bonded/non‑bonded terms, etc.).

Key ideas:

• Force fields are represented by ForceField objects.
• Atom types and other parameter classes live under molpy.core.forcefield.
• Typifiers in molpy.typifier assign types to Atomistic structures.

---

1. ForceField objects¶

The core classes for force fields live in molpy.core.forcefield and represent:

• Atom types (AtomType)
• Bond/angle/dihedral types
• Styles for these interaction types

You typically don’t instantiate these by hand; instead you:

• Load them from files (e.g. LAMMPS force‑field scripts or XML)
• Generate them from higher‑level templates or libraries

Once you have a ForceField, you can pass it to writers such as write_lammps_forcefield or combined helpers like write_lammps_system.

---

2. Typifiers: assigning atom types¶

Typifiers live under molpy.typifier.* and are responsible for taking an Atomistic structure and assigning appropriate atom types and related parameters.

Example (conceptual sketch):

In [1]:

from molpy.typifier.atomistic import OplsAtomisticTypifier

typifier = OplsAtomisticTypifier()
typifier.typify(atomistic)  # modifies atomistic in place with type info

from molpy.typifier.atomistic import OplsAtomisticTypifier typifier = OplsAtomisticTypifier() typifier.typify(atomistic) # modifies atomistic in place with type info

---------------------------------------------------------------------------
TypeError                                 Traceback (most recent call last)
Cell In[1], line 3
      1 from molpy.typifier.atomistic import OplsAtomisticTypifier
----> 3 typifier = OplsAtomisticTypifier()
      4 typifier.typify(atomistic)  # modifies atomistic in place with type info

TypeError: OplsAtomisticTypifier.__init__() missing 1 required positional argument: 'forcefield'

Typical workflow:

1. Build an Atomistic system (monomer, polymer, assembly).
2. Run an appropriate typifier to assign force‑field types.
3. Convert to Frame (if needed) and export using IO writers.

---

3. Loading and exporting force‑field data¶

MolPy provides utilities for loading and writing force‑field data, especially for LAMMPS:

• molpy.io.forcefield.lammps – readers/writers for LAMMPS force‑field scripts.
• write_lammps_forcefield(path, forcefield) – convenience function for writing.
• write_lammps_system(workdir, frame, forcefield) – writes both structure (.data) and force field (.ff) to a directory.

Example:

In [2]:

from molpy.io import write_lammps_system

# frame: Frame with structure and Box
# ff:    ForceField corresponding to the system

write_lammps_system("lammps_system", frame, ff)

from molpy.io import write_lammps_system # frame: Frame with structure and Box # ff: ForceField corresponding to the system write_lammps_system("lammps_system", frame, ff)

---------------------------------------------------------------------------
ImportError                               Traceback (most recent call last)
Cell In[2], line 1
----> 1 from molpy.io import write_lammps_system
      3 # frame: Frame with structure and Box
      4 # ff:    ForceField corresponding to the system
      6 write_lammps_system("lammps_system", frame, ff)

ImportError: cannot import name 'write_lammps_system' from 'molpy.io' (/opt/buildhome/.asdf/installs/python/3.13.3/lib/python3.13/site-packages/molpy/io/__init__.py)

You can then point your engine‑specific input scripts at these files.

---

4. Putting it together¶

The standard force‑field pipeline looks like:

1. Build or import an Atomistic structure.
2. Run a typifier to assign atom types and related parameters.
3. Convert to a Frame (if needed) and attach the ForceField.
4. Use IO writers (e.g. write_lammps_system) to generate input for MD engines.

See also:

• user-guide/molecular-building.md
• user-guide/reaction-modeling.md
• user-guide/simulation-setup.md