Parameterization

The gmso.parameterization module provides functions and classes for applying a ForceField to an un-typed Topology. The primary entry point is apply().

apply

apply() is the main public API for parameterizing a topology. It accepts a ForceField (or a dictionary of forcefields keyed by molecule name) and writes atom types, bond types, angle types, dihedral types, and improper types onto the topology in-place.

gmso.parameterization.parameterize.apply(top, forcefields, match_ff_by='molecule', identify_connections=False, speedup_by_molgraph=False, speedup_by_moltag=False, ignore_params=['improper'], remove_untyped=True, fast_copy=True)[source]

Apply forcefield parameters to a Topology.

Atom-types all sites in top using the supplied forcefield(s) and writes the resulting potential types onto the topology.

Parameters:

  • top (Topology) – The un-typed topology to parameterize.

  • forcefields (Union[ForceField, Dict[str, ForceField]]) – The forcefield(s) to apply. When a single ForceField is supplied it is applied to every site in top. When a dict is supplied, each key must match a molecule name (or group name, see match_ff_by) present in the topology, and the corresponding ForceField is applied only to sites belonging to that molecule/group. A topology with no molecule labels can only accept a single ForceField; passing a dict in that case will raise an error.

  • match_ff_by (str) – Site attribute used to map forcefields when forcefields is a dict. Accepted values: "molecule" or "group".

  • identify_connections (bool) – When True, use NetworkX graph matching to detect angles, dihedrals, and impropers from the bond graph before parameterizing.

  • speedup_by_molgraph (bool) – When True, detect repeated disconnected sub-graphs (molecules) and parameterize each unique molecule only once. Useful for systems with many identical small molecules; may slow down systems with large unique molecules (e.g., monolayers).

  • speedup_by_moltag (bool) – When True, use site.molecule labels to identify repeated molecules and parameterize each unique molecule only once. Requires that molecule and residue labels have been properly assigned.

  • ignore_params (Union[List[str], Set[str], Tuple[str, ...]]) – Connection types whose completeness check is skipped after parameterization. Valid entries: "bond", "angle", "dihedral", "improper". Pass an empty collection to enforce checks for all connection types.

  • remove_untyped (bool) – When True, remove all connections that have no associated connection type after parameterization.

  • fast_copy (bool) – When True, sympy expressions and parameter dictionaries are not deep-copied when the same potential type is assigned to multiple sites or connections. This is significantly faster but means that modifying a parameter on one site/connection will affect all others that share the same AtomType (or connection-type) object. Set to False if you need to modify expressions or parameters after parameterization.

Returns:

The parameterized topology (modified in-place and returned).

Return type:

Topology

Examples

Apply a single forcefield to an entire topology:

>>> from gmso import ForceField
>>> from gmso.parameterization import apply
>>> ff = ForceField("oplsaa.xml")
>>> typed_top = apply(top, ff)

Apply different forcefields to different molecule types:

>>> ff_water = ForceField("spce.xml")
>>> ff_ethanol = ForceField("oplsaa.xml")
>>> typed_top = apply(top, {"water": ff_water, "ethanol": ff_ethanol})