Core Classes

The gmso.core module contains the concrete data structures used to represent a full chemical topology. All classes are importable directly from the gmso namespace.

Topology

Topology is the central data structure in GMSO. It acts as the container for all sites, connections, and forcefield parameters that together describe a molecular system ready for simulation.

Summary

gmso.Topology

A topology.

Reference

class gmso.Topology(name='Topology', box=None)

Bases: object

A topology.

A topology represents a chemical structure wherein lie the collection of sites which together form a chemical structure containing connections (gmso.Bond, gmso.Angle and gmso.Dihedral (along with their associated types). A topology is the fundamental data structure in GMSO, from which we can gather various information about the chemical structure and apply a forcefield before converting the structure into a format familiar to various simulation engines.

Parameters:

• name (str, optional, default 'Topology') – A name for the Topology.

• box (gmso.Box, optional, default None) – A gmso.Box object bounding the topology

typed

True if the topology is typed

Type:

bool

combining_rule

The combining rule for the topology, can be either ‘lorentz’ or ‘geometric’

Type:

str, [``’lorentz’, ``'geometric']

scaling_factors

A collection of scaling factors used in the forcefield

Type:

dict

n_sites

Number of sites in the topology

Type:

int

n_connections

Number of connections in the topology (Bonds, Angles, Dihedrals, Impropers)

Type:

int

n_bonds

Number of bonds in the topology

Type:

int

n_angles

Number of angles in the topology

Type:

int

n_dihedrals

Number of dihedrals in the topology

Type:

int

n_impropers

Number of impropers in the topology

Type:

int

connections

A collection of bonds, angles, dihedrals, and impropers in the topology

Type:

tuple of gmso.Connection objects

bonds

A collection of bonds in the topology

Type:

tuple of gmso.Bond objects

angles

A collection of angles in the topology

Type:

tuple of gmso.Angle objects

dihedrals

A collection of dihedrals in the topology

Type:

tuple of gmso.Dihedral objects

impropers

A collection of impropers in the topology

Type:

tuple of gmso.Improper objects

connection_types

A collection of BondTypes, AngleTypes, DihedralTypes, and ImproperTypes in the topology

Type:

tuple of gmso.Potential objects

atom_types

A collection of AtomTypes in the topology

Type:

tuple of gmso.AtomType objects

bond_types

A collection of BondTypes in the topology

Type:

tuple of gmso.BondType objects

angle_types

A collection go AngleTypes in the topology

Type:

tuple of gmso.AngleType objects

dihedral_types

A collection of DihedralTypes in the topology

Type:

tuple of gmso.DihedralType objects

improper_types

A collection of ImproperTypes in the topology

Type:

tuple of gmso.ImproperType objects

pairpotential_types

A collection of PairPotentialTypes in the topology

Type:

tuple of gmso.PairPotentialType objects

atom_type_expressions

A collection of all the expressions for the AtomTypes in topology

Type:

list of gmso.AtomType.expression objects

connection_type_expressions

A collection of all the expressions for the Potential objects in the topology that represent a connection type

Type:

list of gmso.Potential.expression objects

bond_type_expressions

A collection of all the expressions for the BondTypes in topology

Type:

list of gmso.BondType.expression objects

angle_type_expressions

A collection of all the expressions for the AngleTypes in topology

Type:

list of gmso.AngleType.expression objects

dihedral_type_expressions

A collection of all the expression for the DihedralTypes in the topology

Type:

list of gmso.DihedralType.expression objects

improper_type_expressions

A collection of all the expression for the ImproperTypes in the topology

Type:

list of gmso.ImproperType.expression objects

pairpotential_type_expressions

A collection of all the expression for the PairPotentialTypes in the topology

Type:

list of gmso.PairPotentialType.expression objects

property unit_system

Return the unyt system of the topology.

property name

Return the name of the topology.

property box

Return the Box of the topology.

property typed

Check if the system is parametrized.

property combining_rule

Return the combining rule for the topology.

property scaling_factors

property molecule_scaling_factors

property positions

Return the positions of the sites in the topology.

property n_sites

Return the number of sites in the topology.

property virtual_sites

Return all virtual_sites in the topology.

property n_virtual_sites

Return the number of virtual sites in the topology.

property n_connections

Return the number of connections in the topology.

property n_bonds

Return the number of bonds in the topology.

property n_angles

Return the amount of angles in the topology.

property n_dihedrals

Return the amount of dihedrals in the topology.

property n_impropers

Return the number of impropers in the topology.

property sites

Return all sites in the topology.

property total_charge

Adds all the charges in the topologies

property connections

Return all connections in topology.

property bonds

Return all bonds in the topology.

property angles

Return all angles in the topology.

property dihedrals

Return all dihedrals in the topology.

property impropers

Return all impropers in the topology.

unique_site_labels(label_type='molecule', name_only=False)

Return a list of all molecule/residue labels in the Topology.

property atom_types

Return all atom_types in the topology.

Notes

This returns a TopologyPotentialView object which can be used as an iterator. By default, this will return a view with all the atom_types in the topology (if multiple sites point to the same atom_type, only a single reference is returned/iterated upon). Use, different filters(builtin or custom) to suit your needs. See examples below.

Examples

>>> from gmso.core.atom import Atom
>>> from gmso.core.atom_type import AtomType
>>> from gmso.core.topology import Topology
>>> from gmso.core.views import PotentialFilters
>>> top = Topology(name="my_top")
>>> atom_type = AtomType(name="my_atom_type")
>>> for j in range(100):
...     atom = Atom(name=f"atom_{j+1}")
...     atom.atom_type = atom_type
...     top.add_site(atom)
>>> len(top.atom_types)
1
>>> len(top.atom_types(filter_by=PotentialFilters.REPEAT_DUPLICATES))
100
>>> len(top.atom_types(filter_by=PotentialFilters.UNIQUE_NAME_CLASS))
1

See also

gmso.core.views.TopologyPotentialView

An iterator/filter based view of Potentials in a gmso Topology.

gmso.core.views.PotentialFilters

Builtin filters for viewing potentials in a Topology.

Returns:

An iterator of the atom_types in the system filtered according to the filter function supplied.

Return type:

gmso.core.views.TopologyPotentialView

property connection_types

Return all connection_types in the topology.

Notes

This returns a TopologyPotentialView object which can be used as an iterator.

See also

gmso.core.views.TopologyPotentialView

An iterator/filter based view of Potentials in a gmso Topology.

property bond_types

Return all bond_types in the topology.

Notes

This returns a TopologyPotentialView object which can be used as an iterator.By default, this will return a view with all the bond_types in the topology (if multiple bonds point to the same bond_type, only a single reference is returned/iterated upon). Use, different filters(builtin or custom) to suit your needs. See examples below.

Examples

>>> from gmso.core.atom import Atom
>>> from gmso.core.bond import Bond
>>> from gmso.core.bond_type import BondType
>>> from gmso.core.topology import Topology
>>> from gmso.core.views import PotentialFilters
>>> top = Topology(name="my_top")
>>> for j in range(100):
...     atom1 = Atom(name=f"atom_A_{j+1}")
...     atom2 = Atom(name=f"atom_B_{j+1}")
...     bond = Bond(connection_members=[atom1, atom2])
...     bond.bond_type = BondType(name=f"bond_type", member_types=('atom_A', 'atom_B'))
...     conn = top.add_connection(bond)
>>> len(top.bond_types)
100
>>> len(top.bond_types(filter_by=PotentialFilters.UNIQUE_ID))
100
>>> len(top.bond_types(filter_by=PotentialFilters.UNIQUE_NAME_CLASS))
1

See also

gmso.core.views.TopologyPotentialView

An iterator/filter based view of Potentials in a gmso Topology.

gmso.core.views.PotentialFilters

Builtin filters for viewing potentials in a Topology.

Returns:

An iterator of the bond_types in the system filtered according to the filter function supplied.

Return type:

gmso.core.views.TopologyPotentialView

property angle_types

Return all angle_types in the topology.

Notes

This returns a TopologyPotentialView object which can be used as an iterator. By default, this will return a view with all the angle_types in the topology (if multiple angles point to the same angle_type, only a single reference is returned/iterated upon). Use, different filters(builtin or custom) to suit your needs. See examples below.

Examples

>>> from gmso.core.atom import Atom
>>> from gmso.core.angle import Angle
>>> from gmso.core.angle_type import AngleType
>>> from gmso.core.topology import Topology
>>> from gmso.core.views import PotentialFilters
>>> for j in range(100):
...     atom1 = Atom(name=f"atom_A_{j+1}")
...     atom2 = Atom(name=f"atom_B_{j+1}")
...     atom3 = Atom(name=f"atom_C_{j+1}")
...     angle = Angle(connection_members=[atom1, atom2, atom3])
...     angle.angle_type = AngleType(name=f"angle_type", member_types=('atom_A', 'atom_B', 'atom_C'))
...     conn = top.add_connection(angle)
>>> len(top.angle_types)
100
>>> len(top.angle_types(filter_by=PotentialFilters.UNIQUE_ID))
100
>>> len(top.angle_types(filter_by=PotentialFilters.UNIQUE_NAME_CLASS))
1

See also

gmso.core.views.TopologyPotentialView

An iterator/filter based view of Potentials in a gmso Topology.

gmso.core.views.PotentialFilters

Builtin filters for viewing potentials in a Topology.

Returns:

An iterator of the angle_types in the system filtered according to the filter function supplied.

Return type:

gmso.core.views.TopologyPotentialView

property dihedral_types

Return all dihedral_types in the topology.

Notes

This returns a TopologyPotentialView object which can be used as an iterator. By default, this will return a view with all the dihedral_types in the topology (if multiple dihedrals point to the same dihedral types, only a single reference is returned/iterated upon). Use, different filters(builtin or custom) to suit your needs. See examples below.

Examples

>>> from gmso.core.atom import Atom
>>> from gmso.core.dihedral import Dihedral
>>> from gmso.core.dihedral_type import DihedralType
>>> from gmso.core.topology import Topology
>>> from gmso.core.views import PotentialFilters
>>> for j in range(100):
...     atom1 = Atom(name=f"atom_A_{j+1}")
...     atom2 = Atom(name=f"atom_B_{j+1}")
...     atom3 = Atom(name=f"atom_C_{j+1}")
...     atom4 = Atom(name=f"atom_D_{j+1}")
...     dihedral = Dihedral(connection_members=[atom1, atom2, atom3, atom4])
...     dihedral.dihedral_type = DihedralType(
...         name=f"dihedral_type",
...         member_types=('atom_A', 'atom_B', 'atom_C', 'atom_D')
...     )
...     conn = top.add_connection(dihedral)
>>> len(top.dihedral_types)
100
>>> len(top.dihedral_types(filter_by=PotentialFilters.UNIQUE_ID))
100
>>> len(top.dihedral_types(filter_by=PotentialFilters.UNIQUE_NAME_CLASS))
1

See also

gmso.core.views.TopologyPotentialView

An iterator/filter based view of Potentials in a gmso Topology.

gmso.core.views.PotentialFilters

Builtin filters for viewing potentials in a Topology.

Returns:

An iterator of the dihedral_types in the system filtered according to the filter function supplied.

Return type:

gmso.core.views.TopologyPotentialView

property improper_types

Return all improper_types in the topology.

Notes

This returns a TopologyPotentialView object which can be used as an iterator. By default, this will return a view with all the improper_types in the topology (if multiple impropers point to the same improper_type, only a single reference is returned/iterated upon). Use, different filters(builtin or custom) to suit your needs. See examples below.

Examples

>>> from gmso.core.atom import Atom
>>> from gmso.core.improper import Improper
>>> from gmso.core.improper_type import ImproperType
>>> from gmso.core.topology import Topology
>>> from gmso.core.views import PotentialFilters
>>> for j in range(100):
...     atom1 = Atom(name=f"atom_A_{j+1}")
...     atom2 = Atom(name=f"atom_B_{j+1}")
...     atom3 = Atom(name=f"atom_C_{j+1}")
...     atom4 = Atom(name=f"atom_D_{j+1}")
...     improper = Improper(connection_members=[atom1, atom2, atom3, atom4])
...     improper.improper_type = ImproperType(
...         name=f"dihedral_type",
...         member_types=('atom_A', 'atom_B', 'atom_C', 'atom_D')
...     )
...     conn = top.add_connection(improper)
>>> len(top.improper_types)
100
>>> len(top.improper_types(filter_by=PotentialFilters.UNIQUE_ID))
100
>>> len(top.improper_types(filter_by=PotentialFilters.UNIQUE_NAME_CLASS))
1

See also

gmso.core.views.TopologyPotentialView

An iterator/filter based view of Potentials in a gmso Topology.

gmso.core.views.PotentialFilters

Builtin filters for viewing potentials in a Topology.

Returns:

An iterator of the dihedral_types in the system filtered according to the filter function supplied.

Return type:

gmso.core.views.TopologyPotentialView

property pairpotential_types

property atom_type_expressions

Return all atom_type expressions in the topology.

property connection_type_expressions

Return all connection_type expressions in the topology.

property bond_type_expressions

Return all bond_type expressions in the topology.

property angle_type_expressions

Return all angle_type expressions in the topology.

property dihedral_type_expressions

Return all dihedral_type expressions in the topology.

property improper_type_expressions

Return all improper_type expressions in the topology.

property pairpotential_type_expressions

get_lj_scale(*, molecule_id=None, interaction=None)

Return the selected lj_scales defined for this topology.

set_lj_scale(value, *, molecule_id=None, interaction=None)

Set the correct lj_scaling factors for this topology.

get_scaling_factors(*, molecule_id=None)

Get the scaling factor of this topology or for a particular molecule

set_rigid(molecule)

Set molecule tags to rigid if they match the name or number specified.

Parameters:

molecule (str, Molecule, or tuple of 2) – Specified the molecule name and number to be set rigid. If only string is provided, make all molecule of that name rigid.

remove_site(site)

Remove a site from the topology.

Parameters:

site (gmso.core.Site) – The site to be removed.

Notes

When a site is removed, any connections that site belonged to are also removed.

See also

gmso.core.topology.Topology.iter_connections_by_site

The method that shows all connections belonging to a specific site

remove_connection(connection)

Remove a connection from the topology.

Parameters:

connection (gmso.abc.abstract_conneciton.Connection) – The connection to be removed from the topology

Notes

The sites that belong to this connection are not removed from the topology.

set_scaling_factors(lj, electrostatics, *, molecule_id=None)

Set both lj and electrostatics scaling factors.

get_electrostatics_scale(*, molecule_id=None, interaction=None)

Return the selected electrostatics_scale defined for this topology.

Parameters:

• molecule_id (str, default None) – The molecule id that this scaling factor applies to, if None this will return the Topology’s global scaling factors

• interaction (str, one of {'12', '13', '14'}, default None) – The interaction for which to return the scaling factor for, if None a 3 tuple

Raises:

GMSOError – If the specified parameters can’t return a scaling factor

set_electrostatics_scale(value, *, molecule_id=None, interaction=None)

Set the correct lj_scaling factors for this topology.

Parameters:

• value (float, numpy.ndarray, list, or tuple of floats) – The value to set for this scale

• molecule_id (str, default None) – The molecule id that this scaling factor applies to, if None this will return the Topology’s global scaling factors

• interaction (str, one of {'12', '13', '14'}, default None) – The interaction for which to return the scaling factor for, if None a 3 tuple

Raises:

GMSOError – If the specified parameters can’t return a scaling factor

add_site(site, update_types=False)

Add a site to the topology.

This method will add a site to the existing topology, since sites are stored in an indexed set, adding redundant site will have no effect. If the update_types parameter is set to true (default behavior), this method will also check if there is an gmso.AtomType associated with the site and it to the topology’s AtomTypes collection.

Parameters:

• site (gmso.core.Site) – Site to be added to this topology

• update_types ((bool), default True) – If true, add this site’s atom type to the topology’s set of AtomTypes

add_connection(connection, update_types=False)

Add a gmso.Connection object to the topology.

This method will add a gmso.Connection object to the topology, it can be used to generically include any Connection object i.e. Bond or Angle or Dihedral to the topology. According to the type of object added, the equivalent collection in the topology is updated. For example- If you add a Bond, this method will update topology.connections and topology.bonds object. Additionally, if update_types is True (default behavior), it will also update any Potential objects associated with the connection.

Parameters:

• connection (one of gmso.Connection, gmso.Bond, gmso.Angle, gmso.Dihedral, or gmso.Improper object)

• update_types (bool, default True) – If True also add any Potential object associated with connection to the topology.

Returns:

The Connection object or equivalent Connection object that is in the topology

Return type:

gmso.Connection

identify_connections()

Identify all connections in the topology.

update_atom_types()

Keep an up-to-date length of all the connection types.

update_connection_types()

Keep an up-to-date length of all the connection types.

update_topology()

Update the entire topology.

remove_pairpotentialtype(pair_of_types)

Remove the custom pairwise potential between two AtomTypes/Atomclasses

Parameters:

pair_of_types (list-like of strs) – The pair (or set) of names or atomclasses of gmso.AtomTypes of which the custom pairwise potential should be removed

is_typed(updated=False)

Verify if the topology is parametrized.

is_fully_typed(group='topology', updated=False)

Check if the topology or a specifc group of objects that make up the topology are fully typed

Parameters:

• updated (bool, optional, default False) – If False, will update the atom type and connection type list of the Topology before the checking step.

• group (str, optional, default 'topology') – Specific objects to be checked. Options include: ‘topology’ : check for status of all the topology constituents ‘sites’ : check for status of all topology.sites ‘bonds’ : check for status of all topology.bonds ‘angles’ : check for status of all topology.angles ‘dihedrals’ : check for status of all topology.dihedrals ‘impropers’ : check for status of all topology.impropers

Returns:

Status of the check

Return type:

bool

Notes

self._type is set to True as long as the Topology is at least partially typed.

get_untyped(group)

Get the untyped (non-parametrized) objects of the Topology.

Parameters:

group ({'sites', 'bonds', 'angles', 'dihedrals', 'impropers', 'topology'}) – The group of objects to be checked. The ‘topology’ option will return all untyped object of the topology.

Returns:

untyped – Dictionary of all untyped object, key of the dictionary corresponds to object group names define above.

Return type:

dict

update_angle_types()

Use gmso.Topology.update_connection_types to update AngleTypes in the topology.

This method is an alias for gmso.Topology.update_connection_types.

See also

gmso.Topology.update_connection_types

Update the connection types based on the connection collection in the topology.

update_bond_types()

Use gmso.Topology.update_connection_types to update BondTypes in the topology.

This method is an alias for gmso.Topology.update_connection_types.

See also

gmso.Topology.update_connection_types

Update the connection types based on the connection collection in the topology.

update_dihedral_types()

Use gmso.Topology.update_connection_types to update DihedralTypes in the topology.

This method is an alias for gmso.Topology.update_connection_types.

See also

gmso.Topology.update_connection_types

Update the connection types based on the connection collection in the topology.

update_improper_types()

Use gmso.Topology.update_connection_types to update ImproperTypes in the topology.

This method is an alias for gmso.Topology.update_connection_types.

See also

gmso.Topology.update_connection_types

Update the connection types based on the connection collection in the topology.

get_index(member)

Get index of a member in the topology.

Parameters:

member (gmso Topology objects) – The member to for which to return index for. member can be of type gmso.Site, gmso.Bond, gmso.Angle, gmso.Dihedral, gmso.Improper, gmso.AtomType, gmso.BondType, gmso.AngleType, gmso.DihedralType or gmso.ImproperType.

Returns:

The index of the member in the topology’s collection objects

Return type:

int

write_forcefield(filename, overwrite=False)

Save an xml file for all parameters found in the topology.

Parameters:

• filename (Union[str, pathlib.Path], default None) – The filename to write the XML file to

• overwrite (bool, default False) – If True, overwrite an existing file if it exists

Notes

This method can be used to save a small, trimmed down forcefield from a larger forcefield (e.g. oplsaa). This is useful for editing, saving, and sharing forcefield parameters.

Raises:

GMSOError – If the topology is untyped

to_dataframe(parameter='sites', site_attrs=None, unyts_bool=True)

Return a pandas dataframe object for the sites in a topology

Parameters:

• parameter (str, default 'sites') – A string determining what aspects of the gmso topology will be reported. Options are: ‘sites’, ‘bonds’, ‘angles’, ‘dihedrals’, and ‘impropers’. Defaults to ‘sites’.

• site_attrs (list of str, default None) – List of strings that are attributes of the topology site and can be included as entries in the pandas dataframe. Examples of these can be found by printing topology.sites[0].__dict__. See https://gmso.mosdef.org/en/stable/data_structures.html#gmso.Atom for additional information on labeling.

• unyts_bool (bool, default True) – Determine if numerical values are saved as unyt quantities or floats. See https://unyt.readthedocs.io/en/stable/usage.html for more information about manipulating unyt quantities. Default is True.

Returns:

A pandas.Dataframe object, see https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html for further information.

Return type:

Pandas Dataframe

Examples

Return a dataframe with site names and charges:

>>> topology.to_dataframe(parameter='sites', site_attrs=['charge'])

Return a dataframe listing the sites and parameters for each dihedral:

>>> topology.to_dataframe(parameter='dihedrals', site_attrs=['positions'])

Notes

A dataframe is easily manipulated. To round a column named label to two decimal places:

>>> df['label'] = df['label'].round(2)

To rename a column Atom0 to newname:

>>> df.rename(columns={'Atom0': 'newname'})

See https://pandas.pydata.org/pandas-docs/stable/getting_started/intro_tutorials/index.html for further information.

get_forcefield()

Get an instance of gmso.ForceField out of this topology

Raises:

GMSOError – If the topology is untyped

iter_sites_and_virtual_sites(key, value)

Iterate through this topology’s sites based on certain attribute and their values.

Parameters:

• key (str) – The attribute of the site to look for

• value – The value that the given attribute should be equal to

Yields:

gmso.abc.abstract_site.Site – The site where getattr(site, key) == value

iter_sites(key, value)

Iterate through this topology’s sites based on certain attribute and their values.

Parameters:

• key (str) – The attribute of the site to look for

• value – The value that the given attribute should be equal to

Yields:

gmso.abc.abstract_site.Site – The site where getattr(site, key) == value

iter_sites_by_residue(residue_tag)

Iterate through this topology’s sites which contain this specific residue name.

See also

gmso.core.topology.Topology.iter_sites

The method to iterate over Topology’s sites

iter_sites_by_molecule(molecule_tag)

Iterate through this topology’s sites which contain this specific molecule name.

See also

gmso.core.topology.Topology.iter_sites

The method to iterate over Topology’s sites

iter_connections_by_site(site, connections=None)

Iterate through this topology’s connections which contain this specific site.

Parameters:

• site (gmso.core.Site) – Site to limit connections search to.

• connections (set or list or tuple, optional, default None) – The connection types to include in the search. If None, iterates through all of a site’s connections. Options include “bonds”, “angles”, “dihedrals”, “impropers”

Yields:

gmso.abc.abstract_conneciton.Connection – Connection where site is in Connection.connection_members

create_subtop(label_type, label)

Create a new Topology object from a molecule or graup of the current Topology.

Parameters:

• label_type (str) – Category of the label (“group” or “molecule”)

• label (str (group) or tuple (molecule)) – The label of molecule or group that need to be cloned.

Return type:

gmso.Topology

save(filename, overwrite=False, **kwargs)

Save the topology to a file.

Parameters:

• filename (str, pathlib.Path) – The file to save the topology as

• overwrite (bool, default True) – If True, overwrite the existing file if it exists

• **kwargs – The arguments to specific file savers listed below(as extensions): * json: types, update, indent * gro: precision * lammps/lammpsdata: atom_style

classmethod load(filename, **kwargs)

Load a file to a topology

convert_potential_styles(expressionMap={})

Convert from one parameter form to another.

Parameters:

expressionMap (dict, default {}) – Map where the keys represent the current potential type and the corresponding values represent the desired potential type. The desired potential style can be either a string with the corresponding name, or a gmso.utils.expression.PotentialExpression type.

Examples

# Convert from RB torsions to OPLS torsions top.convert_potential_styles({“dihedrals”: “OPLSTorsionPotential”}) # TODO: convert_potential_styles with PotentialExpression

convert_unit_styles(unitsystem, exp_unitsDict)

Convert from one set of base units to another.

Parameters:

• unitsystem (unyt.UnitSystem) – set of base units to use for all expressions of the topology in unyt package <https://unyt.readthedocs.io/en/stable/>_

• exp_unitsDict (dict) – keys with topology attributes that should be converted and values with dictionary of parameter: expected_dimension

Examples

>>> top.convert_unit_styles(
...     u.UnitSystem("lammps_real", "Å", "amu", "fs", "K", "rad"),
...     {"bond": {"k": "energy/length**2", "r_eq": "length"}},
... )

Sites

Sites are the fundamental interaction points in a topology. GMSO ships two concrete site types: Atom for element-bearing particles, and VirtualSite for massless interaction centres (e.g., TIP4P water models).

gmso.Atom	An atom represents a single element association in a topology.
gmso.VirtualSite	A generalized virtual site class in GMSO.

Atom

class gmso.Atom(**data)

Bases: Site

An atom represents a single element association in a topology.

Atoms are the representation of an element within gmso that describes any general atom in a molecular simulation. Atoms also contain information that are unique to elements vs other types of interaction sites in molecular simulations. For example, charge, mass, and periodic table information.

Notes

Atoms have all the attributes inherited from the base Site class, The order of precedence when attaining properties charge and mass is:

1. atom.charge > atom.atom_type.charge

2. atom.mass > atom.atom_type.mass

Examples

>>> from gmso.core.atom import Atom
>>> atom1 = Atom(name='lithium')

See also

gmso.abc.AbstractSite

An Abstract Base class for implementing site objects in GMSO. The class Atom bases from the gmso.abc.abstract site class

charge_: unyt_quantity | float | None

mass_: unyt_quantity | float | None

element_: Element | None

atom_type_: AtomType | None

restraint_: dict | None

property charge: unyt_quantity | None

Return the charge of the atom.

property mass: unyt_quantity | None

Return the mass of the atom.

property element: Element | None

Return the element associated with the atom.

property atom_type: AtomType | property

Return the atom_type associated with the atom.

property restraint

Return the restraint of this atom.

serialize_charge(charge_)

serialize_mass(mass_)

serialize_restraint(restraint_)

clone()

Clone this atom.

classmethod is_valid_charge(charge)

Ensure that the charge is physically meaningful.

classmethod is_valid_mass(mass)

Ensure that the mass is physically meaningful.

VirtualSite

class gmso.VirtualSite(**data)

Bases: Site

A generalized virtual site class in GMSO.

Virtual sites are massless particles that represent off-atom charge/interaction sites, lone pairs, or other non-physical sites.

charge

The charge of the virtual site in elementary charge units. Will prioritize self.virtual_type.charge.

Type:

u.unyt_array

parent_sites

The real constituent sites that define the virtual site’s position.

Type:

List[Site]

virtual_type

The type information, including parameters for virtual_position and virtual_potential, used to define the virtual site’s interactions and positions

Type:

gmso.core.virtual_type.VirtualType

parent_sites_: List[Site]

charge_: unyt_quantity

position_: Callable

virtual_type_: VirtualType | None

property parent_sites: List[Site]

Reminder that the order of sites is fixed, such that site index 1 corresponds to ri in the self.virtual_type.virtual_position expression.

position()

On the fly position evaluation from virtual_type.virtual_position and parent_sites.

Return type:

unyt_array

property virtual_type

Return the virtual site type if the virtual site is parametrized.

property charge: unyt_quantity | None

Return the charge of the virtual site.

property molecule: Molecule | None

Return the molecule associated with the parent sites.

Connections

Connections encode the covalent topology of a system. They are built from ordered sequences of Atom members and an optional connection type that carries the forcefield parameters.

Bonded connections must be defined, either in the file used to create the gmso.Topology or in the conversion from another object into a gmso.Topology. If the bond connections are correctly identified, you can use gmso.utils.connectivity.identify_connections() to infer and populate the rest of the connections (i.e., angles, dihedrals and improper dihedrals.)

gmso.Bond	A 2-partner connection between sites.
gmso.Angle	A 3-partner connection between Atoms.
gmso.Dihedral	A 4-partner connection between sites.
gmso.Improper	A 4-partner connection between sites.

Bond

class gmso.Bond(**data)

Bases: Connection

A 2-partner connection between sites.

This is a subclass of the gmso.abc.Connection superclass. This class has strictly 2 members in its connection_members. The connection_type in this class corresponds to gmso.BondType.

Notes

Inherits some methods from Connection: __eq__, __repr__, _validate methods.

Additional _validate methods are presented.

connectivity: ClassVar[Tuple[Tuple[int]]] = ((0, 1),)

connection_members_: Tuple[Atom, Atom]

bond_type_: BondType | None

restraint_: dict | None

bond_order_: float | None

property bond_type

Return parameters of the potential type.

property connection_type

Return parameters of the potential type.

property restraint

Return the restraint of this bond.

property bond_order

Return the bond_order of this bond.

equivalent_members()

Get a set of the equivalent connection member tuples.

Returns:

A unique set of tuples of equivalent connection members

Return type:

frozenset

Notes

For a bond:

i, j == j, i

where i and j are the connection members.

Angle

class gmso.Angle(**data)

Bases: Connection

A 3-partner connection between Atoms.

This is a subclass of the gmso.Connection superclass. This class has strictly 3 members in its connection members. The connection_type in this class corresponds to gmso.AngleType.

Notes

Inherits some methods from Connection: __eq__, __repr__, _validate methods

Additional _validate methods are presented.

self.connectivity is the associated indices that defines the way connection_members are bonded to match self.bonds.

connectivity: ClassVar[Tuple[Tuple[int]]] = ((0, 1), (1, 2))

connection_members_: Tuple[Atom, Atom, Atom]

bonds_: Tuple[Bond, Bond]

angle_type_: AngleType | None

restraint_: dict | None

property angle_type

Return the angle type if the angle is parametrized.

property connection_type

Return the angle type if the angle is parametrized.

property restraint

Return the restraint of this angle.

property bonds

Return a tuple of gmso.core.Bond objects that correspond to this angle.

property bonds_orders

Return the bond_order strings of this angle.

equivalent_members()

Return a set of the equivalent connection member tuples.

Returns:

A unique set of tuples of equivalent connection members

Return type:

frozenset

Notes

For an angle:

i, j, k == k, j, i

where i, j and k are the connection members.

classmethod set_dependent_value_default(data)

Automatically set bonds for this angle if connection_members is defined.

Dihedral

class gmso.Dihedral(**data)

Bases: Connection

A 4-partner connection between sites.

This is a subclass of the gmso.Connection superclass. This class has strictly 4 members in its connection_members. The connection_type in this class corresponds to gmso.DihedralType. The connectivity of a dihedral is: m1–m2–m3–m4

where m1, m2, m3, and m4 are connection members 1-4, respectively.

Notes

Inherits some methods from Connection: __eq__, __repr__, _validate methods

Additional _validate methods are presented.

connectivity: ClassVar[Tuple[Tuple[int]]] = ((0, 1), (1, 2), (2, 3))

connection_members_: Tuple[Atom, Atom, Atom, Atom]

bonds_: Tuple[Bond, Bond, Bond]

dihedral_type_: DihedralType | None

restraint_: dict | None

property dihedral_type

property connection_type

property restraint

Return the restraint of this dihedral.

property bonds

Return the bonds that makeup this dihedral.

Connectivity is ((0,1), (1,2), (2,3))

property bonds_orders

Return the bond_order strings of this dihedral.

equivalent_members()

Get a set of the equivalent connection member tuples

Returns:

A unique set of tuples of equivalent connection members

Return type:

frozenset

Notes

For a dihedral:

i, j, k, l == l, k, j, i

where i, j, k, and l are the connection members.

classmethod set_dependent_value_default(data)

Automatically set bonds for this dihedral if connection_members is defined.

Improper

class gmso.Improper(**data)

Bases: Connection

A 4-partner connection between sites.

This is a subclass of the gmso.Connection superclass. This class has strictly 4 members in its connection_members. The connection_type in this class corresponds to gmso.ImproperType The connectivity of an improper is:

m2

m3 - m1 - m4

where m1, m2, m3, and m4 are connection members 1-4, respectively.

Notes

Inherits some methods from Connection: __eq__, __repr__, _validate methods

Additional _validate methods are presented.

connectivity: ClassVar[Tuple[Tuple[int]]] = ((0, 1), (0, 2), (0, 3))

connection_members_: Tuple[Atom, Atom, Atom, Atom]

bonds_: Tuple[Bond, Bond, Bond]

improper_type_: ImproperType | None

bond_orders_: Tuple[str, str] | None

property improper_type

Return Potential object for this connection if it exists.

property connection_type

Return Potential object for this connection if it exists.

property bonds

Return the bonds that makeup this Improper.

Connectivity is ((0,1), (0,2), (0,3))

property bonds_orders

Return the bond_order strings of this improper.

equivalent_members()

Get a set of the equivalent connection member tuples.

Returns:

A unique set of tuples of equivalent connection members

Return type:

frozenset

Notes

For an improper:

i, j, k, l == i, k, j, l

where i, j, k, and l are the connection members.

classmethod set_dependent_value_default(data)

Automatically set bonds for this improper if connection_members is defined.

Potential Types

Potential types carry the functional form and parameters for a given interaction class. They attach to the corresponding connection (or site) via the *_type attributes.

gmso.AtomType	A description of non-bonded interactions between sites.
gmso.BondType	A descripton of the interaction between 2 bonded partners.
gmso.AngleType	A descripton of the interaction between 3 bonded partners.
gmso.DihedralType	A descripton of the interaction between 4 bonded partners.
gmso.ImproperType	A description of the interaction between 4 bonded partners.
gmso.PairPotentialType	A description of custom pairwise potential between 2 AtomTypes that does not follow combination rule.
gmso.VirtualType	A generalized virtual site type class in GMSO.

AtomType

class gmso.AtomType(name='AtomType', mass=unyt_quantity(0., 'g/mol'), charge=unyt_quantity(0., 'C'), expression=None, parameters=None, potential_expression=None, independent_variables=None, atomclass='', doi='', overrides=None, definition='', description='', tags=None)

Bases: ParametricPotential

A description of non-bonded interactions between sites.

This is a subclass of the gmso.core.Potential superclass.

AtomType represents an atom type and includes the functional form describing its interactions and, optionally, other properties such as mass and charge. This class inhereits from Potential, which stores the non-bonded interaction between atoms or sites. The functional form of the potential is stored as a sympy expression and the parameters, with units, are stored explicitly.

mass_: unyt_array | None

charge_: unyt_array | None

atomclass_: str | None

doi_: str | None

overrides_: Set[str] | None

definition_: str | None

description_: str | None

property charge

Return the charge of the atom_type.

property mass

Return the mass of the atom_type.

property atomclass

Return the atomclass of the atom_type.

property doi

Return the doi of the atom_type.

property overrides

Return the overrides of the atom_type.

property description

Return the description of the atom_type.

property definition

Return the SMARTS string of the atom_type.

serialize_charge(charge_)

serialize_mass(mass_)

clone(fast_copy=False)

Clone this AtomType, faster alternative to deepcopying.

classmethod validate_mass(mass)

Check to see that a mass is a unyt array of the right dimension.

classmethod validate_charge(charge)

Check to see that a charge is a unyt array of the right dimension.

BondType

class gmso.BondType(name='BondType', expression=None, parameters=None, independent_variables=None, potential_expression=None, member_types=None, member_classes=None, identifier=None, tags=None)

Bases: ParametricPotential

A descripton of the interaction between 2 bonded partners.

This is a subclass of the gmso.core.Potential superclass.

BondType represents a bond type and includes the functional form describing its interactions. The functional form of the potential is stored as a sympy expression and the parameters, with units, are stored explicitly. The AtomTypes that are used to define the bond type are stored as member_types.

Notes

Inherits many functions from gmso.ParametricPotential: __eq__, _validate functions.

member_types_: Tuple[str, str] | None

member_classes_: Tuple[str, str] | None

identifier_: str | None

property member_types

Return the members involved in this bondtype.

property member_classes

property identifier

AngleType

class gmso.AngleType(name='AngleType', expression=None, parameters=None, independent_variables=None, potential_expression=None, member_types=None, member_classes=None, identifier=None, tags=None)

Bases: ParametricPotential

A descripton of the interaction between 3 bonded partners.

This is a subclass of the gmso.core.Potential superclass.

AngleType represents an angle type and includes the functional form describing its interactions. The functional form of the potential is stored as a sympy expression and the parameters, with units, are stored explicitly. The AtomTypes that are used to define the angle type are stored as member_types.

Notes

Inherits many functions from gmso.ParametricPotential: __eq__, _validate functions.

member_types_: Tuple[str, str, str] | None

member_classes_: Tuple[str, str, str] | None

identifier_: str | None

property member_types

property member_classes

property identifier

DihedralType

class gmso.DihedralType(name='DihedralType', expression=None, parameters=None, independent_variables=None, potential_expression=None, member_types=None, member_classes=None, identifier=None, tags=None)

Bases: ParametricPotential

A descripton of the interaction between 4 bonded partners.

This is a subclass of the gmso.core.Potential superclass.

DihedralType represents a dihedral type and includes the functional form describing its interactions. The functional form of the potential is stored as a sympy expression and the parameters, with units, are stored explicitly. The AtomTypes that are used to define the dihedral type are stored as member_types.

The connectivity of a dihedral is:

m1–m2–m3–m4

where m1, m2, m3, and m4 are connection members 1-4, respectively.

Notes

Inherits many functions from gmso.ParametricPotential: __eq__, _validate functions.

member_types_: Tuple[str, str, str, str] | None

member_classes_: Tuple[str, str, str, str] | None

identifier_: str | None

property member_types

property member_classes

property identifier

ImproperType

class gmso.ImproperType(name='ImproperType', expression=None, parameters=None, independent_variables=None, potential_expression=None, member_types=None, member_classes=None, identifier=None, tags=None)

Bases: ParametricPotential

A description of the interaction between 4 bonded partners.

This is a subclass of the gmso.core.Potential superclass.

ImproperType represents a improper type and includes the functional form describing its interactions. The functional form of the potential is stored as a sympy expression and the parameters, with units, are stored explicitly. The AtomTypes that are used to define the improper type are stored as member_types. The connectivity of an improper is:

m2

m3 - m1 - m4

where m1, m2, m3, and m4 are connection members 1-4, respectively.

Notes

Inherits many functions from gmso.ParametricPotential: __eq__, _validate functions.

member_types_: Tuple[str, str, str, str] | None

member_classes_: Tuple[str, str, str, str] | None

identifier_: str | None

property member_types

Return member information for this ImproperType.

property member_classes

property identifier

PairPotentialType

class gmso.PairPotentialType(name='PairPotentialType', expression=None, parameters=None, independent_variables=None, potential_expression=None, member_types=None, identifier=None, tags=None)

Bases: ParametricPotential

A description of custom pairwise potential between 2 AtomTypes that does not follow combination rule.

This is a subclass of the gmso.core.ParametricPotential superclass.

PairPotentialType represents a type of pairwise potential between two Atomtypes that does not follow a specific combination rule, and includes the functional form describing its interactions. The functional form of the potential is stored as a sympy expression and the parameters, with units, are stored explicitly. The AtomTypes that are used to define the dihedral type are stored as member_types.

Notes

Inherits many functions from gmso.ParametricPotential:

__eq__, _validate functions

member_types_: Tuple[str, str] | None

identifier_: str | None

property member_types

property identifier

VirtualType

class gmso.VirtualType(**data)

Bases: GMSOBase

A generalized virtual site type class in GMSO.

Virtual sites are massless particles that represent off-atom interaction/charge sites, lone pairs, or other non-physical sites.

name

A generalized name for the type of the virtual site. See https://manual.gromacs.org/current/reference-manual/functions/interaction-methods.html#id3 for some Gromacs examples.

Type:

str

member_types_

The atom types of the constituent atoms that define the virtual site’s position.

Type:

List[Str]

member_classes_

The atom classes of the constituent atoms that define the virtual site’s position.

Type:

List[Str]

charge

The charge of the virtual site in elementary charge units.

Type:

u.unyt_array

virtual_potential

The ParametricPotential that takes the specific parent_atoms and is used to generate the specific virtual site position.

Type:

gmso.core.virtual_type.VirtualPositionType

virtual_position

The ParametricPotential that is used to store the nonbonded interactions of the virtual site type.

Type:

gmso.core.virtual_type.VirtualPotentialType

name_: str

member_types_: Tuple[str, ...] | None

member_classes_: Tuple[str, ...] | None

identifier_: str | None

charge_: unyt_array | None

position_: Callable

virtual_position_: VirtualPositionType | None

virtual_potential_: VirtualPotentialType | None

doi_: str | None

property name: str

property virtual_position: VirtualPositionType

property virtual_potential: VirtualPotentialType

property member_types

property member_classes

property identifier

property charge

property doi

Return the doi of the virtual_type.

classmethod validate_charge(charge)

Check to see that a charge is a unyt array of the right dimension.

serialize_charge(charge_)

clone(fast_copy=False)

Clone this VirtualType.

get_parameters(copy=False)

Return parameters for this VirtualPotentialType and VirtualPositionType.

etree(units=None)

Return an lxml.ElementTree for the parametric potential adhering to gmso XML schema

ForceField

ForceField parses and stores the potential types and parameters defined in a forcefield XML file (Foyer/OpenMM format). It is the primary input to gmso.parameterization.apply().

gmso.ForceField

A generic implementation of the forcefield class.

class gmso.ForceField(xml_loc=None, strict=True, greedy=True, backend='forcefield-utilities')

Bases: object

A generic implementation of the forcefield class.

The ForceField class is one of the core data structures in gmso, which is used to hold a collection of gmso.core.Potential subclass objects along with some metadata to represent a forcefield. The forcefield object can be applied to any gmso.Topology which has effects on its Sites, Bonds, Angles and Dihedrals.

Parameters:

• xml_loc (str) – Path to the forcefield xml. The forcefield xml can be either in Foyer or GMSO style.

• strict (bool, default True) – If true, perform a strict validation of the forcefield XML file

• greedy (bool, default True) – If True, when using strict mode, fail on the first error/mismatch

• backend (str, default "forcefield-utilities") – Can be “gmso” or “forcefield-utilities”. This will define the methods to load the forcefield.

name

Name of the forcefield

Type:

str

version

Version of the forcefield

Type:

str

atom_types

A collection of atom types in the forcefield

Type:

dict

bond_types

A collection of bond types in the forcefield

Type:

dict

angle_types

A collection of angle types in the forcefield

Type:

dict

dihedral_types

A collection of dihedral types in the forcefield

Type:

dict

units

A collection of unyt.Unit objects used in the forcefield

Type:

dict

scaling_factors

A collection of scaling factors used in the forcefield

Type:

dict

See also

gmso.ForceField.from_xml

A class method to create forcefield object from XML files

gmso.utils.ff_utils.validate

Function to validate the gmso XML file

property non_element_types

Get the non-element types in the ForceField.

property atom_class_groups

Return a dictionary of atomClasses in the Forcefield.

group_atom_types_by_expression()

Return all AtomTypes in this ForceField with grouped by expression.

See also

_group_by_expression

Groups a dictionary of gmso.ParametricPotentials by their expression

Returns:

A dictionary where the key, value -> expression, list of atom_types with that expression

Return type:

dict

group_bond_types_by_expression()

Return all BondTypes in this ForceField with grouped by expression.

See also

_group_by_expression

Groups a dictionary of gmso.ParametricPotentials by their expression

Returns:

A dictionary where the key, value -> expression, list of BondTypes with that expression

Return type:

dict

group_angle_types_by_expression()

Return all AngleTypes in this ForceField with grouped by expression.

See also

_group_by_expression

Groups a dictionary of gmso.ParametricPotentials by their expression

Returns:

A dictionary where the key, value -> expression, list of AngleTypes with that expression

Return type:

dict

group_dihedral_types_by_expression()

Return all DihedralTypes in this ForceField with grouped by expression.

See also

_group_by_expression

Groups a dictionary of gmso.ParametricPotentials by their expression

Returns:

A dictionary where the key, value -> expression, list of DihedralTypes with that expression

Return type:

dict

group_improper_types_by_expression()

Return all ImproperTypes in this ForceField with grouped by expression.

See also

_group_by_expression

Groups a dictionary of gmso.ParametricPotentials by their expression

Returns:

A dictionary where the key, value -> expression, list of ImproperTypes with that expression

Return type:

dict

group_pairpotential_types_by_expression()

Return all PairPotentialTypes in this ForceField with grouped by expression

See also

_group_by_expression

Groups a dictionary of gmso.ParametricPotentials by their expression

Returns:

A dictionary where the key, value -> expression, list of PairPotentialTypes with that expression

Return type:

dict

group_virtual_types_by_expression()

Return all VirtualTypes in this ForceField with grouped by expression.

See also

_group_by_expression

Groups a dictionary of gmso.ParametricPotentials by their expression

Returns:

A dictionary where the key, value -> expression, list of VirtualTypes with that expression

Return type:

dict

get_potential(group, key, exact_match=False)

Return a specific potential by key in this ForceField.

Parameters:

• group ({'atom_type', 'bond_type', 'angle_type', 'dihedral_type', 'improper_type', 'virtual_type'}) – The potential group to perform this search on

• key (str (for atom type) or list of str (for connection types)) – The key to lookup for this potential group

• exact_match (bool, default False) – If False, use wildcard matching to check for valid matches in the forcefield.

Returns:

The parametric potential requested

Return type:

gmso.ParametricPotential

Raises:

MissingPotentialError – When the potential specified by key is not found in the ForceField potential group group

get_parameters(group, key, exact_match=False, copy=False)

Return parameters for a specific potential by key in this ForceField.

This function uses the get_potential function to get Parameters

See also

gmso.ForceField.get_potential

Get specific potential/parameters from a forcefield potential group by key

classmethod xml_from_forcefield_utilities(filename)

to_xml(filename, overwrite=False, backend='gmso')

Get an lxml ElementTree representation of this ForceField

Parameters:

• filename (Union[str, pathlib.Path], default None) – The filename to write the XML file to

• overwrite (bool, default False) – If True, overwrite an existing file if it exists

• backend (str, default "gmso") – Can be “gmso” or “forcefield-utilities”. This will define the methods to write the xml.

classmethod from_xml(xmls_or_etrees, strict=True, greedy=True)

Create a gmso.Forcefield object from XML File(s).

This class method creates a ForceField object from the reference XML file. This method takes in a single or collection of XML files with information about gmso.AtomTypes, gmso.BondTypes, gmso.AngleTypes , gmso.PairPotentialTypes and gmso.DihedralTypes to create the ForceField object.

Parameters:

• xmls_or_etrees (Union[str, Iterable[str], etree._ElementTree, Iterable[etree._ElementTree]]) – The forcefield XML locations or XML Element Trees

• strict (bool, default True) – If true, perform a strict validation of the forcefield XML file

• greedy (bool, default True) – If True, when using strict mode, fail on the first error/mismatch

Returns:

forcefield – A gmso.Forcefield object with a collection of Potential objects created using the information in the XML file

Return type:

gmso.ForceField

Box

Box stores periodic boundary information for a simulation cell.

class gmso.Box(lengths, angles=None)

Bases: object

A box that bounds a Topology.

The Box data structure contains the relevant information to fully describe a simulation box in three dimensions, including lengths, angles, and vectors

It is based on the Bravais lattice concept. A 3-dimensional prism can be fully described with 6 parameters, the lengths of the 3 edges of the prism (a,`b`,`c`); and the 3 interplanar angles that describe the tilt of the prism edges (alpha, beta, gamma). For example, the Bravais parameters where a=b=c, and alpha=beta=gamma=90 define a cubic prism (cube).

Parameters:

• lengths (array-like, shape(3,), dtype=float) – Lengths of the box [a, b, c]. Units are assumed to be in nm; if passed in as a unyt_array it will be converted to nm; if passed in as floats, nm is assumed.

• angles (array-like, optional, shape(3,), dtype=float) – Interplanar angles, [alpha, beta, gamma], that describe the box shape. Units are assumed to be in degrees; if passed in as a unyt_array it will be converted to degrees; if passed in as floats, degrees are assumed.

a, b, c

Lengths of the box.

Type:

float

alpha, beta, gamma

Interplanar angles fully describing the Box.

Type:

float

get_vectors()

Output the vectors describing the shape of the Box.

get_unit_vectors()

Output the unit vectors describing the shape of the Box.

property lengths

Return edge lengths of the box.

property angles

Return angles of the box.

get_vectors()

Return the vectors of the box.

get_unit_vectors()

Return the normalized vectors of the box.

json_dict()

Element

Element provides periodic-table data (mass, symbol, atomic number, etc.).

class gmso.Element(**data)

Bases: GMSOBase

Chemical element object

Template to create a chemical element. Properties of the element instance are immutable. All known elements are pre-built and stored internally.

name: str

symbol: str

atomic_number: int

mass: unyt_quantity

serialize_mass(mass)