Data Structures in GMSO

Following data structures are available within GMSO.

Core Classes

gmso.Topology A topology.
gmso.SubTopology A sub-topology i.e.
gmso.Atom An atom represents a single element association in a topology.
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.
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.

Topology

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

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
Variables:
  • typed (bool) – True if the topology is typed
  • combining_rule (str, ['lorentz', 'geometric']) – The combining rule for the topology, can be either ‘lorentz’ or ‘geometric’
  • scaling_factors (dict) – A collection of scaling factors used in the forcefield
  • n_sites (int) – Number of sites in the topology
  • n_connections (int) – Number of connections in the topology (Bonds, Angles, Dihedrals, Impropers)
  • n_bonds (int) – Number of bonds in the topology
  • n_angles (int) – Number of angles in the topology
  • n_dihedrals (int) – Number of dihedrals in the topology
  • n_impropers (int) – Number of impropers in the topology
  • n_subtops (int) – Number of subtopolgies in the topology
  • connections (tuple of gmso.Connection objects) – A collection of bonds, angles, dihedrals, and impropers in the topology
  • bonds (tuple of gmso.Bond objects) – A collection of bonds in the topology
  • angles (tuple of gmso.Angle objects) – A collection of angles in the topology
  • dihedrals (tuple of gmso.Dihedral objects) – A collection of dihedrals in the topology
  • impropers (tuple of gmso.Improper objects) – A collection of impropers in the topology
  • connection_types (tuple of gmso.Potential objects) – A collection of BondTypes, AngleTypes, DihedralTypes, and ImproperTypes in the topology
  • atom_types (tuple of gmso.AtomType objects) – A collection of AtomTypes in the topology
  • bond_types (tuple of gmso.BondType objects) – A collection of BondTypes in the topology
  • angle_types (tuple of gmso.AngleType objects) – A collection go AngleTypes in the topology
  • dihedral_types (tuple of gmso.DihedralType objects) – A collection of DihedralTypes in the topology
  • improper_types (tuple of gmso.ImproperType objects) – A collection of ImproperTypes in the topology
  • atom_type_expressions (list of gmso.AtomType.expression objects) – A collection of all the expressions for the AtomTypes in topology
  • connection_type_expressions (list of gmso.Potential.expression objects) – A collection of all the expressions for the Potential objects in the topology that represent a connection type
  • bond_type_expressions (list of gmso.BondType.expression objects) – A collection of all the expressions for the BondTypes in topology
  • angle_type_expressions (list of gmso.AngleType.expression objects) – A collection of all the expressions for the AngleTypes in topology
  • dihedral_type_expressions (list of gmso.DihedralType.expression objects) – A collection of all the expression for the DihedralTypes in the topology
  • improper_type_expressions (list of gmso.ImproperType.expression objects) – A collection of all the expression for the ImproperTypes in the topology

See also

gmso.SubTopology
A topology within a topology
add_connection(connection, update_types=True)[source]

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

add_site(site, update_types=True)[source]

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_subtopology(subtop, update=True)[source]

Add a sub-topology to this topology

This methods adds a gmso.Core.SubTopology object to the topology All the sites in this sub-topology are added to the collection of current sites in this topology.

Parameters:
  • subtop (gmso.SubTopology) – The sub-topology object to be added.
  • update (bool, default=True)

See also

gmso.SubTopology()
A topology within a topology
get_index(member)[source]

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
update_angle_types()[source]

Uses 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_atom_types()[source]

Update atom types in the topology

This method checks all the sites in the topology which have an associated AtomType and if that AtomType is not in the topology’s AtomTypes collection, it will add it there.

gmso.Topology.update_connection_types :
Update the connection types based on the connection collection in the topology
update_bond_types()[source]

Uses 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_connection_types()[source]

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

This method looks into all the connection objects (Bonds, Angles, Dihedrals, Impropers) to check if any Potential object (BondType, AngleType, DihedralType, ImproperType) is not in the topology’s respective collection and will add those objects there.

See also

gmso.Topology.update_atom_types()
Update atom types in the topology.
update_dihedral_types()[source]

Uses 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()[source]

Uses 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.
update_sites()[source]

Update the sites of the topology.

This method will update the sites in the topology based on the connection members, For example- if you add a bond to a topology, without adding the constituent sites, this method can be called to add the sites which are the connection members of the bond as shown below.

>>> import gmso
>>> site1 = gmso.Site(name='MySite1')
>>> site2 = gmso.Site(name='MySite2')
>>> bond1 = gmso.Bond(name='site1-site2', connection_members=[site1, site2])
>>> this_topology = gmso.Topology('TwoSitesTopology')
>>> this_topology.add_connection(bond1)
>>> this_topology.update_sites()

See also

gmso.Topology.add_site()
Add a site to the topology.
gmso.Topology.add_connection()
Add a Bond, an Angle or a Dihedral to the topology.
gmso.Topology.update_topology()
Update the entire topology.
update_topology()[source]

Update the entire topology

SubTopology

class gmso.SubTopology(name='Sub-Topology', parent=None)[source]

A sub-topology i.e. topology within a topology

This class provides a hierarchical topological representation to the topology as it imperative with many chemical structures to have separation of layers/ boundaries. A sub-topology can be added to a gmso.Topology object which will be the parent of the sub-topology.

Parameters:
  • name (str, optional, default=’Sub-Topology’) – Name of the sub-topology
  • parent (gmso.Topology, optional, default=None) – The parent topology of this SubTopology
Variables:
  • sites (IndexedSet of gmso.Site objects) – Collection of sites within this sub-topology
  • n_sites (int) – Number of sites withing this sub-topology
add_site(site, update_types=True)[source]

Add a site to this sub-topology

This method adds a site to the sub-topology. If the sub-topology has a parent, the site will also be added to the parent topology. 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 sub-topology’s AtomTypes collection.

Parameters:
  • site (gmso.Atom) – The site to be added to this sub-topology
  • update_types ((bool), default=True) – If true, add this site’s atom type to the sub-topology’s set of AtomTypes
Raises:

TypeError – If the parameter site is not of type topology.Site

Atom

class gmso.Atom(name="''", label="''", position=None, charge=None, mass=None, element=None, atom_type=None)[source]

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.

Parameters:
  • name (str, default=’’) – Name of the atom, defaults to class name
  • label (str, default=’’) – Label to be assigned to the atom
  • position (Union[Sequence[float], numpy.ndarray, unyt.array.unyt_array], default=None) – The 3D Cartesian coordinates of the position of the atom
  • charge (Union[unyt.array.unyt_quantity, float, NoneType], default=None) – Charge of the atom
  • mass (Union[unyt.array.unyt_quantity, float, NoneType], default=None) – Mass of the atom
  • element (<class ‘gmso.core.element.Element’>, default=None) – Element associated with the atom
  • atom_type (<class ‘gmso.core.atom_type.AtomType’>, default=None) – AtomType associated with the atom

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
classmethod construct(_fields_set: Optional[SetStr] = None, **values) → Model

Creates a new model setting __dict__ and __fields_set__ from trusted or pre-validated data. Default values are respected, but no other validation is performed. Behaves as if Config.extra = ‘allow’ was set since it adds all passed values

copy

Duplicate a model, optionally choose which fields to include, exclude and change.

Parameters:
  • include – fields to include in new model
  • exclude – fields to exclude from new model, as with values this takes precedence over include
  • update – values to change/add in the new model. Note: the data is not validated before creating the new model: you should trust this data
  • deep – set to True to make a deep copy of the model
Returns:

new model instance

dict

Generate a dictionary representation of the model, optionally specifying which fields to include or exclude.

classmethod is_valid_position(position)

Validator for attribute position

json

Generate a JSON representation of the model, include and exclude arguments as per dict().

encoder is an optional function to supply as default to json.dumps(), other arguments as per json.dumps().

classmethod update_forward_refs(**localns) → None

Try to update ForwardRefs on fields based on this Model, globalns and localns.

Bond

class gmso.Bond(name="''", connection_members=None, bond_type=None)[source]

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.

Parameters:
  • name (str, default=’’) – Name of the bond. Defaults to class name
  • bond_members (Tuple[gmso.core.atom.Atom, gmso.core.atom.Atom], default=None) – The 2 atoms involved in the bond.
  • bond_type (<class ‘gmso.core.bond_type.BondType’>, default=None) – BondType of this bond.

Notes

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

Additional _validate methods are presented.

classmethod construct(_fields_set: Optional[SetStr] = None, **values) → Model

Creates a new model setting __dict__ and __fields_set__ from trusted or pre-validated data. Default values are respected, but no other validation is performed. Behaves as if Config.extra = ‘allow’ was set since it adds all passed values

copy

Duplicate a model, optionally choose which fields to include, exclude and change.

Parameters:
  • include – fields to include in new model
  • exclude – fields to exclude from new model, as with values this takes precedence over include
  • update – values to change/add in the new model. Note: the data is not validated before creating the new model: you should trust this data
  • deep – set to True to make a deep copy of the model
Returns:

new model instance

dict

Generate a dictionary representation of the model, optionally specifying which fields to include or exclude.

equivalent_members()[source]

Get a set of the equivalent connection member tuples :returns: A unique set of tuples of equivalent connection members :rtype: frozenset

Notes

For a bond:
i, j == j, i

where i and j are the connection members.

json

Generate a JSON representation of the model, include and exclude arguments as per dict().

encoder is an optional function to supply as default to json.dumps(), other arguments as per json.dumps().

classmethod update_forward_refs(**localns) → None

Try to update ForwardRefs on fields based on this Model, globalns and localns.

Angle

class gmso.Angle(name="''", connection_members=None, angle_type=None)[source]

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.

Parameters:
  • name (str, default=’’) – Name of the angle. Defaults to class name
  • angle_members (Tuple[gmso.core.atom.Atom, gmso.core.atom.Atom, gmso.core.atom.Atom], default=None) – The 3 atoms involved in the angle.
  • angle_type (<class ‘gmso.core.angle_type.AngleType’>, default=None) – AngleType of this angle.

Notes

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

Additional _validate methods are presented

classmethod construct(_fields_set: Optional[SetStr] = None, **values) → Model

Creates a new model setting __dict__ and __fields_set__ from trusted or pre-validated data. Default values are respected, but no other validation is performed. Behaves as if Config.extra = ‘allow’ was set since it adds all passed values

copy

Duplicate a model, optionally choose which fields to include, exclude and change.

Parameters:
  • include – fields to include in new model
  • exclude – fields to exclude from new model, as with values this takes precedence over include
  • update – values to change/add in the new model. Note: the data is not validated before creating the new model: you should trust this data
  • deep – set to True to make a deep copy of the model
Returns:

new model instance

dict

Generate a dictionary representation of the model, optionally specifying which fields to include or exclude.

equivalent_members()[source]

Get a set of the equivalent connection member tuples :returns: A unique set of tuples of equivalent connection members :rtype: frozenset

Notes

For an angle:
i, j, k == k, j, i

where i, j and k are the connection members.

json

Generate a JSON representation of the model, include and exclude arguments as per dict().

encoder is an optional function to supply as default to json.dumps(), other arguments as per json.dumps().

classmethod update_forward_refs(**localns) → None

Try to update ForwardRefs on fields based on this Model, globalns and localns.

Dihedral

class gmso.Dihedral(name="''", connection_members=None, dihedral_type=None)[source]

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.

Parameters:
  • name (str, default=’’) – Name of the dihedral. Defaults to class name
  • dihedral_members (Tuple[gmso.core.atom.Atom, gmso.core.atom.Atom, gmso.core.atom.Atom, gmso.core.atom.Atom], default=None) – The 4 atoms involved in the dihedral.
  • dihedral_type (<class ‘gmso.core.dihedral_type.DihedralType’>, default=None) – DihedralType of this dihedral.

Notes

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

Additional _validate methods are presented

classmethod construct(_fields_set: Optional[SetStr] = None, **values) → Model

Creates a new model setting __dict__ and __fields_set__ from trusted or pre-validated data. Default values are respected, but no other validation is performed. Behaves as if Config.extra = ‘allow’ was set since it adds all passed values

copy

Duplicate a model, optionally choose which fields to include, exclude and change.

Parameters:
  • include – fields to include in new model
  • exclude – fields to exclude from new model, as with values this takes precedence over include
  • update – values to change/add in the new model. Note: the data is not validated before creating the new model: you should trust this data
  • deep – set to True to make a deep copy of the model
Returns:

new model instance

dict

Generate a dictionary representation of the model, optionally specifying which fields to include or exclude.

equivalent_members()[source]

Get a set of the equivalent connection member tuples :returns: A unique set of tuples of equivalent connection members :rtype: frozenset

Notes

For a dihedral:
i, j, k, l == l, k, j, i

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

json

Generate a JSON representation of the model, include and exclude arguments as per dict().

encoder is an optional function to supply as default to json.dumps(), other arguments as per json.dumps().

classmethod update_forward_refs(**localns) → None

Try to update ForwardRefs on fields based on this Model, globalns and localns.

Improper

class gmso.Improper(name="''", connection_members=None, improper_type=None)[source]

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 | m1 / m3 m4

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

Parameters:
  • name (str, default=’’) – Name of the improper. Defaults to class name
  • improper_members (Tuple[gmso.core.atom.Atom, gmso.core.atom.Atom, gmso.core.atom.Atom, gmso.core.atom.Atom], default=None) – The 4 atoms of this improper. Central site first, then the three atoms connected to the central site.
  • improper_type (<class ‘gmso.core.improper_type.ImproperType’>, default=None) – ImproperType of this improper.

Notes

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

Additional _validate methods are presented

classmethod construct(_fields_set: Optional[SetStr] = None, **values) → Model

Creates a new model setting __dict__ and __fields_set__ from trusted or pre-validated data. Default values are respected, but no other validation is performed. Behaves as if Config.extra = ‘allow’ was set since it adds all passed values

copy

Duplicate a model, optionally choose which fields to include, exclude and change.

Parameters:
  • include – fields to include in new model
  • exclude – fields to exclude from new model, as with values this takes precedence over include
  • update – values to change/add in the new model. Note: the data is not validated before creating the new model: you should trust this data
  • deep – set to True to make a deep copy of the model
Returns:

new model instance

dict

Generate a dictionary representation of the model, optionally specifying which fields to include or exclude.

equivalent_members()[source]

Get a set of the equivalent connection member tuples :returns: A unique set of tuples of equivalent connection members :rtype: frozenset

Notes

For an improper:
i, j, k, l == i, k, j, l

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

json

Generate a JSON representation of the model, include and exclude arguments as per dict().

encoder is an optional function to supply as default to json.dumps(), other arguments as per json.dumps().

classmethod update_forward_refs(**localns) → None

Try to update ForwardRefs on fields based on this Model, globalns and localns.

Potential Classes

AtomType

class gmso.AtomType(name='AtomType', mass=unyt_quantity(0., 'g/mol'), charge=unyt_quantity(0., 'C'), expression='4*epsilon*((sigma/r)**12 - (sigma/r)**6)', parameters=None, independent_variables=None, atomclass='', doi='', overrides=None, definition='', description='', tags=None, topology=None)[source]

A description of non-bonded interactions between sites.

Parameters:
  • tags (Any, default={}) – Tags associated with the metadata
  • name (str, default=’’) – The name of the potential. Defaults to class name
  • topology (Any, default=None) – the topology of which this potential is a part of
  • mass (unyt_array, default=0.0 g/mol) – The mass of the atom type
  • charge (unyt_array, default=0.0 C) – The charge of the atom type
  • atomclass (str, default=’’) – The class of the atomtype
  • doi (str, default=’’) – Digital Object Identifier of publication where this atom type was introduced
  • overrides (str, default=set()) – Set of other atom types that this atom type overrides
  • definition (str, default=’’) – SMARTS string defining this atom type
  • description (str, default=’’) – Description for the AtomType
  • expression (Optional[Union[str, sympy.Expr]], default=4*epsilon*((sigma/r)**12 - (sigma/r)**6)) – The mathematical expression of the functional form of the potential
  • parameters (Optional[dict], default=None) – The parameters of the Potential expression and their corresponding values, as unyt quantities
  • independent_variables (Optional[Union[set, str]], default=None) – The independent variables in the Potential’s expression
add_tag(tag: str, value: Any, overwrite=True) → None

Add metadata for a particular tag

classmethod construct(_fields_set: Optional[SetStr] = None, **values) → Model

Creates a new model setting __dict__ and __fields_set__ from trusted or pre-validated data. Default values are respected, but no other validation is performed. Behaves as if Config.extra = ‘allow’ was set since it adds all passed values

copy

Duplicate a model, optionally choose which fields to include, exclude and change.

Parameters:
  • include – fields to include in new model
  • exclude – fields to exclude from new model, as with values this takes precedence over include
  • update – values to change/add in the new model. Note: the data is not validated before creating the new model: you should trust this data
  • deep – set to True to make a deep copy of the model
Returns:

new model instance

dict

Generate a dictionary representation of the model, optionally specifying which fields to include or exclude.

expression

Optional[Union[str, sympy.Expr]] The mathematical expression of the functional form of the potential

classmethod from_template(potential_template, parameters, topology=None)

Create a potential object from the potential_template

Parameters:
  • potential_template (gmso.lib.potential_templates.PotentialTemplate,) – The potential template object
  • parameters (dict,) – The parameters of the potential object to create
  • topology (gmso.Topology, default=None) – The topology to which the created potential object belongs to
Returns:

The potential object created

Return type:

gmso.ParametricPotential

Raises:

GMSOError – If potential_template is not of instance PotentialTemplate

get_parameters(copy=False)

Returns parameters for this ParametricPotential

get_tag(tag: str, throw=False) → Any

Get value of a particular tag

independent_variables

Optional[Union[set, str]] The independent variables in the Potential’s expression

json

Generate a JSON representation of the model, include and exclude arguments as per dict().

encoder is an optional function to supply as default to json.dumps(), other arguments as per json.dumps().

parameters

Optional[dict] The parameters of the Potential expression and their corresponding values, as unyt quantities

set_expression(expression=None, parameters=None, independent_variables=None)

Set the expression, parameters, and independent variables for this potential.

Parameters:
  • expression (sympy.Expression or string) – The mathematical expression corresponding to the potential If None, the expression remains unchanged
  • parameters (dict) – {parameter: value} in the expression If None, the parameters remain unchanged

Notes

Be aware of the symbols used in the expression and parameters. If unnecessary parameters are supplied, an error is thrown. If only a subset of the parameters are supplied, they are updated while the non-passed parameters default to the existing values

classmethod update_forward_refs(**localns) → None

Try to update ForwardRefs on fields based on this Model, globalns and localns.

classmethod validate_charge(charge)[source]

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

classmethod validate_mass(mass)[source]

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

BondType

class gmso.BondType(name='BondType', expression='0.5 * k * (r-r_eq)**2', parameters=None, independent_variables=None, member_types=None, topology=None, tags=None)[source]

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.

Parameters:
  • tags (Any, default={}) – Tags associated with the metadata
  • name (str, default=’’) – The name of the potential. Defaults to class name
  • topology (Any, default=None) – the topology of which this potential is a part of
  • member_types (Tuple[str, str], default=None) – List-like of of gmso.AtomType.name or gmso.AtomType.atomclass defining the members of this bond type
  • expression (Optional[Union[str, sympy.Expr]], default=0.5 * k * (r-r_eq)**2) – The mathematical expression of the functional form of the potential
  • parameters (Optional[dict], default=None) – The parameters of the Potential expression and their corresponding values, as unyt quantities
  • independent_variables (Optional[Union[set, str]], default=None) – The independent variables in the Potential’s expression

Notes

Inherits many functions from gmso.ParametricPotential:
__eq__, _validate functions
add_tag(tag: str, value: Any, overwrite=True) → None

Add metadata for a particular tag

classmethod construct(_fields_set: Optional[SetStr] = None, **values) → Model

Creates a new model setting __dict__ and __fields_set__ from trusted or pre-validated data. Default values are respected, but no other validation is performed. Behaves as if Config.extra = ‘allow’ was set since it adds all passed values

copy

Duplicate a model, optionally choose which fields to include, exclude and change.

Parameters:
  • include – fields to include in new model
  • exclude – fields to exclude from new model, as with values this takes precedence over include
  • update – values to change/add in the new model. Note: the data is not validated before creating the new model: you should trust this data
  • deep – set to True to make a deep copy of the model
Returns:

new model instance

dict

Generate a dictionary representation of the model, optionally specifying which fields to include or exclude.

expression

Optional[Union[str, sympy.Expr]] The mathematical expression of the functional form of the potential

classmethod from_template(potential_template, parameters, topology=None)

Create a potential object from the potential_template

Parameters:
  • potential_template (gmso.lib.potential_templates.PotentialTemplate,) – The potential template object
  • parameters (dict,) – The parameters of the potential object to create
  • topology (gmso.Topology, default=None) – The topology to which the created potential object belongs to
Returns:

The potential object created

Return type:

gmso.ParametricPotential

Raises:

GMSOError – If potential_template is not of instance PotentialTemplate

get_parameters(copy=False)

Returns parameters for this ParametricPotential

get_tag(tag: str, throw=False) → Any

Get value of a particular tag

independent_variables

Optional[Union[set, str]] The independent variables in the Potential’s expression

json

Generate a JSON representation of the model, include and exclude arguments as per dict().

encoder is an optional function to supply as default to json.dumps(), other arguments as per json.dumps().

parameters

Optional[dict] The parameters of the Potential expression and their corresponding values, as unyt quantities

set_expression(expression=None, parameters=None, independent_variables=None)

Set the expression, parameters, and independent variables for this potential.

Parameters:
  • expression (sympy.Expression or string) – The mathematical expression corresponding to the potential If None, the expression remains unchanged
  • parameters (dict) – {parameter: value} in the expression If None, the parameters remain unchanged

Notes

Be aware of the symbols used in the expression and parameters. If unnecessary parameters are supplied, an error is thrown. If only a subset of the parameters are supplied, they are updated while the non-passed parameters default to the existing values

classmethod update_forward_refs(**localns) → None

Try to update ForwardRefs on fields based on this Model, globalns and localns.

AngleType

class gmso.AngleType(name='AngleType', expression='0.5 * k * (theta-theta_eq)**2', parameters=None, independent_variables=None, member_types=None, topology=None, tags=None)[source]

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.

Parameters:
  • tags (Any, default={}) – Tags associated with the metadata
  • name (str, default=’’) – The name of the potential. Defaults to class name
  • topology (Any, default=None) – the topology of which this potential is a part of
  • member_types (Tuple[str, str, str], default=None) – List-like of gmso.AtomType.name or gmso.AtomType.atomclass defining the members of this angle type
  • expression (Optional[Union[str, sympy.Expr]], default=0.5 * k * (theta-theta_eq)**2) – The mathematical expression of the functional form of the potential
  • parameters (Optional[dict], default=None) – The parameters of the Potential expression and their corresponding values, as unyt quantities
  • independent_variables (Optional[Union[set, str]], default=None) – The independent variables in the Potential’s expression

Notes

Inherits many functions from gmso.ParametricPotential:
__eq__, _validate functions
add_tag(tag: str, value: Any, overwrite=True) → None

Add metadata for a particular tag

classmethod construct(_fields_set: Optional[SetStr] = None, **values) → Model

Creates a new model setting __dict__ and __fields_set__ from trusted or pre-validated data. Default values are respected, but no other validation is performed. Behaves as if Config.extra = ‘allow’ was set since it adds all passed values

copy

Duplicate a model, optionally choose which fields to include, exclude and change.

Parameters:
  • include – fields to include in new model
  • exclude – fields to exclude from new model, as with values this takes precedence over include
  • update – values to change/add in the new model. Note: the data is not validated before creating the new model: you should trust this data
  • deep – set to True to make a deep copy of the model
Returns:

new model instance

dict

Generate a dictionary representation of the model, optionally specifying which fields to include or exclude.

expression

Optional[Union[str, sympy.Expr]] The mathematical expression of the functional form of the potential

classmethod from_template(potential_template, parameters, topology=None)

Create a potential object from the potential_template

Parameters:
  • potential_template (gmso.lib.potential_templates.PotentialTemplate,) – The potential template object
  • parameters (dict,) – The parameters of the potential object to create
  • topology (gmso.Topology, default=None) – The topology to which the created potential object belongs to
Returns:

The potential object created

Return type:

gmso.ParametricPotential

Raises:

GMSOError – If potential_template is not of instance PotentialTemplate

get_parameters(copy=False)

Returns parameters for this ParametricPotential

get_tag(tag: str, throw=False) → Any

Get value of a particular tag

independent_variables

Optional[Union[set, str]] The independent variables in the Potential’s expression

json

Generate a JSON representation of the model, include and exclude arguments as per dict().

encoder is an optional function to supply as default to json.dumps(), other arguments as per json.dumps().

parameters

Optional[dict] The parameters of the Potential expression and their corresponding values, as unyt quantities

set_expression(expression=None, parameters=None, independent_variables=None)

Set the expression, parameters, and independent variables for this potential.

Parameters:
  • expression (sympy.Expression or string) – The mathematical expression corresponding to the potential If None, the expression remains unchanged
  • parameters (dict) – {parameter: value} in the expression If None, the parameters remain unchanged

Notes

Be aware of the symbols used in the expression and parameters. If unnecessary parameters are supplied, an error is thrown. If only a subset of the parameters are supplied, they are updated while the non-passed parameters default to the existing values

classmethod update_forward_refs(**localns) → None

Try to update ForwardRefs on fields based on this Model, globalns and localns.

DihedralType

class gmso.DihedralType(name='DihedralType', expression='k * (1 + cos(n * phi - phi_eq))**2', parameters=None, independent_variables=None, member_types=None, topology=None, tags=None)[source]

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.

Parameters:
  • tags (Any, default={}) – Tags associated with the metadata
  • name (str, default=’’) – The name of the potential. Defaults to class name
  • topology (Any, default=None) – the topology of which this potential is a part of
  • member_types (Tuple[str, str, str, str], default=None) – List-like of of gmso.AtomType.name or gmso.AtomType.atomclass defining the members of this dihedral type
  • expression (Optional[Union[str, sympy.Expr]], default=k * (1 + cos(n * phi - phi_eq))**2) – The mathematical expression of the functional form of the potential
  • parameters (Optional[dict], default=None) – The parameters of the Potential expression and their corresponding values, as unyt quantities
  • independent_variables (Optional[Union[set, str]], default=None) – The independent variables in the Potential’s expression

Notes

Inherits many functions from gmso.ParametricPotential:
__eq__, _validate functions
add_tag(tag: str, value: Any, overwrite=True) → None

Add metadata for a particular tag

classmethod construct(_fields_set: Optional[SetStr] = None, **values) → Model

Creates a new model setting __dict__ and __fields_set__ from trusted or pre-validated data. Default values are respected, but no other validation is performed. Behaves as if Config.extra = ‘allow’ was set since it adds all passed values

copy

Duplicate a model, optionally choose which fields to include, exclude and change.

Parameters:
  • include – fields to include in new model
  • exclude – fields to exclude from new model, as with values this takes precedence over include
  • update – values to change/add in the new model. Note: the data is not validated before creating the new model: you should trust this data
  • deep – set to True to make a deep copy of the model
Returns:

new model instance

dict

Generate a dictionary representation of the model, optionally specifying which fields to include or exclude.

expression

Optional[Union[str, sympy.Expr]] The mathematical expression of the functional form of the potential

classmethod from_template(potential_template, parameters, topology=None)

Create a potential object from the potential_template

Parameters:
  • potential_template (gmso.lib.potential_templates.PotentialTemplate,) – The potential template object
  • parameters (dict,) – The parameters of the potential object to create
  • topology (gmso.Topology, default=None) – The topology to which the created potential object belongs to
Returns:

The potential object created

Return type:

gmso.ParametricPotential

Raises:

GMSOError – If potential_template is not of instance PotentialTemplate

get_parameters(copy=False)

Returns parameters for this ParametricPotential

get_tag(tag: str, throw=False) → Any

Get value of a particular tag

independent_variables

Optional[Union[set, str]] The independent variables in the Potential’s expression

json

Generate a JSON representation of the model, include and exclude arguments as per dict().

encoder is an optional function to supply as default to json.dumps(), other arguments as per json.dumps().

parameters

Optional[dict] The parameters of the Potential expression and their corresponding values, as unyt quantities

set_expression(expression=None, parameters=None, independent_variables=None)

Set the expression, parameters, and independent variables for this potential.

Parameters:
  • expression (sympy.Expression or string) – The mathematical expression corresponding to the potential If None, the expression remains unchanged
  • parameters (dict) – {parameter: value} in the expression If None, the parameters remain unchanged

Notes

Be aware of the symbols used in the expression and parameters. If unnecessary parameters are supplied, an error is thrown. If only a subset of the parameters are supplied, they are updated while the non-passed parameters default to the existing values

classmethod update_forward_refs(**localns) → None

Try to update ForwardRefs on fields based on this Model, globalns and localns.

ImproperType

class gmso.ImproperType(name='ImproperType', expression='0.5 * k * ((phi - phi_eq))**2', parameters=None, independent_variables=None, member_types=None, topology=None, tags=None)[source]

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 | m1 / m3 m4

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

Parameters:
  • tags (Any, default={}) – Tags associated with the metadata
  • name (str, default=’’) – The name of the potential. Defaults to class name
  • topology (Any, default=None) – the topology of which this potential is a part of
  • member_types (Tuple[str, str, str, str], default=None) – List-like of of gmso.AtomType.name or gmso.AtomType.atomclass defining the members of this improper type
  • expression (Optional[Union[str, sympy.Expr]], default=0.5 * k * ((phi - phi_eq))**2) – The mathematical expression of the functional form of the potential
  • parameters (Optional[dict], default=None) – The parameters of the Potential expression and their corresponding values, as unyt quantities
  • independent_variables (Optional[Union[set, str]], default=None) – The independent variables in the Potential’s expression

Notes

Inherits many functions from gmso.ParametricPotential:
__eq__, _validate functions
add_tag(tag: str, value: Any, overwrite=True) → None

Add metadata for a particular tag

classmethod construct(_fields_set: Optional[SetStr] = None, **values) → Model

Creates a new model setting __dict__ and __fields_set__ from trusted or pre-validated data. Default values are respected, but no other validation is performed. Behaves as if Config.extra = ‘allow’ was set since it adds all passed values

copy

Duplicate a model, optionally choose which fields to include, exclude and change.

Parameters:
  • include – fields to include in new model
  • exclude – fields to exclude from new model, as with values this takes precedence over include
  • update – values to change/add in the new model. Note: the data is not validated before creating the new model: you should trust this data
  • deep – set to True to make a deep copy of the model
Returns:

new model instance

dict

Generate a dictionary representation of the model, optionally specifying which fields to include or exclude.

expression

Optional[Union[str, sympy.Expr]] The mathematical expression of the functional form of the potential

classmethod from_template(potential_template, parameters, topology=None)

Create a potential object from the potential_template

Parameters:
  • potential_template (gmso.lib.potential_templates.PotentialTemplate,) – The potential template object
  • parameters (dict,) – The parameters of the potential object to create
  • topology (gmso.Topology, default=None) – The topology to which the created potential object belongs to
Returns:

The potential object created

Return type:

gmso.ParametricPotential

Raises:

GMSOError – If potential_template is not of instance PotentialTemplate

get_parameters(copy=False)

Returns parameters for this ParametricPotential

get_tag(tag: str, throw=False) → Any

Get value of a particular tag

independent_variables

Optional[Union[set, str]] The independent variables in the Potential’s expression

json

Generate a JSON representation of the model, include and exclude arguments as per dict().

encoder is an optional function to supply as default to json.dumps(), other arguments as per json.dumps().

parameters

Optional[dict] The parameters of the Potential expression and their corresponding values, as unyt quantities

set_expression(expression=None, parameters=None, independent_variables=None)

Set the expression, parameters, and independent variables for this potential.

Parameters:
  • expression (sympy.Expression or string) – The mathematical expression corresponding to the potential If None, the expression remains unchanged
  • parameters (dict) – {parameter: value} in the expression If None, the parameters remain unchanged

Notes

Be aware of the symbols used in the expression and parameters. If unnecessary parameters are supplied, an error is thrown. If only a subset of the parameters are supplied, they are updated while the non-passed parameters default to the existing values

classmethod update_forward_refs(**localns) → None

Try to update ForwardRefs on fields based on this Model, globalns and localns.

ForceField

class gmso.ForceField(xml_loc=None, strict=True, greedy=True)[source]

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:
  • name (str) – Name of the forcefield, default ‘ForceField’
  • version (str) – a cannonical semantic version of the forcefield, default 1.0.0
  • 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
Variables:
  • name (str) – Name of the forcefield
  • version (str) – Version of the forcefield
  • atom_types (dict) – A collection of atom types in the forcefield
  • bond_types (dict) – A collection of bond types in the forcefield
  • angle_types (dict) – A collection of angle types in the forcefield
  • dihedral_types (dict) – A collection of dihedral types in the forcefield
  • units (dict) – A collection of unyt.Unit objects used in the forcefield
  • scaling_factors (dict) – A collection of scaling factors used in the forcefield

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
atom_class_groups

Return a dictionary of atomClasses in the Forcefield

classmethod from_xml(xmls_or_etrees, strict=True, greedy=True)[source]

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

This class method creates a ForceFiled 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 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

get_parameters(group, key, warn=False, copy=False)[source]

Returns 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
get_potential(group, key, warn=False)[source]

Returns a specific potential by key in this ForceField

Parameters:
  • group ({‘atom_types’, ‘bond_types’, ‘angle_types’, ‘dihedral_types’, ‘improper_types’}) – The potential group to perform this search on
  • key (str or list of str) – The key to lookup for this potential group
  • warn (bool, default=False) – If true, raise a warning instead of Error if no match found
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

group_angle_types_by_expression()[source]

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_atom_types_by_expression()[source]

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()[source]

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_dihedral_types_by_expression()[source]

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()[source]

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