# 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 topologyVariables:

typed(bool) – True if the topology is typedcombining_rule(str,['lorentz','geometric']) – The combining rule for the topology, can be either ‘lorentz’ or ‘geometric’n_sites(int) – Number of sites in the topologyn_connections(int) – Number of connections in the topology (Bonds, Angles, Dihedrals, Impropers)n_bonds(int) – Number of bonds in the topologyn_angles(int) – Number of angles in the topologyn_dihedrals(int) – Number of dihedrals in the topologyn_impropers(int) – Number of impropers in the topologyn_subtops(int) – Number of subtopolgies in the topologyconnections(tuple of gmso.Connection objects) – A collection of bonds, angles, dihedrals, and impropers in the topologybonds(tuple of gmso.Bond objects) – A collection of bonds in the topologyangles(tuple of gmso.Angle objects) – A collection of angles in the topologydihedrals(tuple of gmso.Dihedral objects) – A collection of dihedrals in the topologyimpropers(tuple of gmso.Improper objects) – A collection of impropers in the topologyconnection_types(tuple of gmso.Potential objects) – A collection of BondTypes, AngleTypes, DihedralTypes, and ImproperTypes in the topologyatom_types(tuple of gmso.AtomType objects) – A collection of AtomTypes in the topologybond_types(tuple of gmso.BondType objects) – A collection of BondTypes in the topologyangle_types(tuple of gmso.AngleType objects) – A collection go AngleTypes in the topologydihedral_types(tuple of gmso.DihedralType objects) – A collection of DihedralTypes in the topologyimproper_types(tuple of gmso.ImproperType objects) – A collection of ImproperTypes in the topologyatom_type_expressions(list of gmso.AtomType.expression objects) – A collection of all the expressions for the AtomTypes in topologyconnection_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 typebond_type_expressions(list of gmso.BondType.expression objects) – A collection of all the expressions for the BondTypes in topologyangle_type_expressions(list of gmso.AngleType.expression objects) – A collection of all the expressions for the AngleTypes in topologydihedral_type_expressions(list of gmso.DihedralType.expression objects) – A collection of all the expression for the DihedralTypes in the topologyimproper_type_expressions(list of gmso.ImproperType.expression objects) – A collection of all the expression for the ImproperTypes in the topologySee 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 topologyupdate_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.

### 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-topologyparent(gmso.Topology, optional, default=None) – The parent topology of this SubTopologyVariables:

sites(IndexedSet of gmso.Site objects) – Collection of sites within this sub-topologyn_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-topologyupdate_types((bool), default=True) – If true, add this site’s atom type to the sub-topology’s set of AtomTypesRaises:

`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 namelabel(str, default=’‘) – Label to be assigned to the atomposition(Union[Sequence[float], numpy.ndarray, unyt.array.unyt_array], default=None) – The 3D Cartesian coordinates of the position of the atomcharge(Union[unyt.array.unyt_quantity, float, NoneType], default=None) – Charge of the atommass(Union[unyt.array.unyt_quantity, float, NoneType], default=None) – Mass of the atomelement(<class ‘gmso.core.element.Element’>, default=None) – Element associated with the atomatom_type(<class ‘gmso.core.atom_type.AtomType’>, default=None) – AtomType associated with the atomNotes

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

- atom.charge > atom.atom_type.charge
- 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.

`copy`

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

Parameters:

include– fields to include in new modelexclude– fields to exclude from new model, as with values this takes precedence over includeupdate– values to change/add in the new model. Note: the data is not validated before creating the new model: you should trust this datadeep– set to True to make a deep copy of the modelReturns: 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=Ellipsis,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 namebond_members(Tuple[gmso.core.atom.Atom, gmso.core.atom.Atom], default=Ellipsis) – 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.

`copy`

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

Parameters:

include– fields to include in new modelexclude– fields to exclude from new model, as with values this takes precedence over includeupdate– values to change/add in the new model. Note: the data is not validated before creating the new model: you should trust this datadeep– set to True to make a deep copy of the modelReturns: 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=Ellipsis,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 nameangle_members(Tuple[gmso.core.atom.Atom, gmso.core.atom.Atom, gmso.core.atom.Atom], default=Ellipsis) – 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.

`copy`

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

Parameters:

include– fields to include in new modelexclude– fields to exclude from new model, as with values this takes precedence over includeupdate– values to change/add in the new model. Note: the data is not validated before creating the new model: you should trust this datadeep– set to True to make a deep copy of the modelReturns: 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=Ellipsis,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–m4where m1, m2, m3, and m4 are connection members 1-4, respectively.

Parameters:

name(str, default=’‘) – Name of the dihedral. Defaults to class namedihedral_members(Tuple[gmso.core.atom.Atom, gmso.core.atom.Atom, gmso.core.atom.Atom, gmso.core.atom.Atom], default=Ellipsis) – 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¶

`copy`

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

Parameters:

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

`dict`

¶

`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().

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=Ellipsis,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 m4where m1, m2, m3, and m4 are connection members 1-4, respectively.

Parameters:

name(str, default=’‘) – Name of the improper. Defaults to class nameimproper_members(Tuple[gmso.core.atom.Atom, gmso.core.atom.Atom, gmso.core.atom.Atom, gmso.core.atom.Atom], default=Ellipsis) – 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¶

`copy`

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

Parameters:

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

`dict`

¶

`equivalent_members`

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

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='',topology=None)[source]¶A description of non-bonded interactions between sites.

Parameters:

name(str, default=’‘) – The name of the potential. Defaults to class nametopology(Any, default=None) – the topology of which this potential is a part ofmass(unyt_array, default=0.0 g/mol) – The mass of the atom typecharge(unyt_array, default=0.0 C) – The charge of the atom typeatomclass(str, default=’‘) – The class of the atomtypedoi(str, default=’‘) – Digital Object Identifier of publication where this atom type was introducedoverrides(str, default=set()) – Set of other atom types that this atom type overridesdefinition(str, default=’‘) – SMARTS string defining this atom typedescription(str, default=’‘) – Description for the AtomTypeexpression(Optional[Union[str, sympy.Expr]], default=4*epsilon*((sigma/r)**12 - (sigma/r)**6)) – The mathematical expression of the functional form of the potentialparameters(Optional[dict], default=None) – The parameters of the Potential expression and their corresponding values, as unyt quantitiesindependent_variables(Optional[Union[set, str]], default=None) – The independent variables in the Potential’s expression

classmethod`construct`

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

`copy`

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

Parameters:

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

`dict`

¶

`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 objectparameters(dict,) – The parameters of the potential object to createtopology(gmso.Topology, default=None) – The topology to which the created potential object belongs toReturns: The potential object created

Return type: gmso.ParametricPotential

Raises:

`GMSOError`

– If potential_template is not of instance PotentialTemplate

`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().

`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 unchangedparameters(dict) – {parameter: value} in the expression If None, the parameters remain unchangedNotes

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.

### BondType¶

class`gmso.`

`BondType`

(name='BondType',expression='0.5 * k * (r-r_eq)**2',parameters=None,independent_variables=None,member_types=None,topology=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:

name(str, default=’‘) – The name of the potential. Defaults to class nametopology(Any, default=None) – the topology of which this potential is a part ofmember_types(Tuple[str, str], default=None) – List-like of of gmso.AtomType.name or gmso.AtomType.atomclass defining the members of this bond typeexpression(Optional[Union[str, sympy.Expr]], default=0.5 * k * (r-r_eq)**2) – The mathematical expression of the functional form of the potentialparameters(Optional[dict], default=None) – The parameters of the Potential expression and their corresponding values, as unyt quantitiesindependent_variables(Optional[Union[set, str]], default=None) – The independent variables in the Potential’s expressionNotes

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

classmethod`construct`

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

`copy`

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

Parameters:

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

`dict`

¶

`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 objectparameters(dict,) – The parameters of the potential object to createtopology(gmso.Topology, default=None) – The topology to which the created potential object belongs toReturns: The potential object created

Return type: gmso.ParametricPotential

Raises:

`GMSOError`

– If potential_template is not of instance PotentialTemplate

`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().

`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 unchangedparameters(dict) – {parameter: value} in the expression If None, the parameters remain unchangedNotes

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)[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:

name(str, default=’‘) – The name of the potential. Defaults to class nametopology(Any, default=None) – the topology of which this potential is a part ofmember_types(Tuple[str, str, str], default=None) – List-like of gmso.AtomType.name or gmso.AtomType.atomclass defining the members of this angle typeexpression(Optional[Union[str, sympy.Expr]], default=0.5 * k * (theta-theta_eq)**2) – The mathematical expression of the functional form of the potentialparameters(Optional[dict], default=None) – The parameters of the Potential expression and their corresponding values, as unyt quantitiesindependent_variables(Optional[Union[set, str]], default=None) – The independent variables in the Potential’s expressionNotes

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

classmethod`construct`

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

`copy`

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

Parameters:

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

`dict`

¶

`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 objectparameters(dict,) – The parameters of the potential object to createtopology(gmso.Topology, default=None) – The topology to which the created potential object belongs toReturns: The potential object created

Return type: gmso.ParametricPotential

Raises:

`GMSOError`

– If potential_template is not of instance PotentialTemplate

`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().

`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 unchangedparameters(dict) – {parameter: value} in the expression If None, the parameters remain unchangedNotes

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)[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–m4where m1, m2, m3, and m4 are connection members 1-4, respectively.

Parameters:

name(str, default=’‘) – The name of the potential. Defaults to class nametopology(Any, default=None) – the topology of which this potential is a part ofmember_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 typeexpression(Optional[Union[str, sympy.Expr]], default=k * (1 + cos(n * phi - phi_eq))**2) – The mathematical expression of the functional form of the potentialparameters(Optional[dict], default=None) – The parameters of the Potential expression and their corresponding values, as unyt quantitiesindependent_variables(Optional[Union[set, str]], default=None) – The independent variables in the Potential’s expressionNotes

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

classmethod`construct`

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

`copy`

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

Parameters:

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

`dict`

¶

`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 objectparameters(dict,) – The parameters of the potential object to createtopology(gmso.Topology, default=None) – The topology to which the created potential object belongs toReturns: The potential object created

Return type: gmso.ParametricPotential

Raises:

`GMSOError`

– If potential_template is not of instance PotentialTemplate

`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().

`parameters`

¶

`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 unchangedparameters(dict) – {parameter: value} in the expression If None, the parameters remain unchangedNotes

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)[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 m4where m1, m2, m3, and m4 are connection members 1-4, respectively.

Parameters:

name(str, default=’‘) – The name of the potential. Defaults to class nametopology(Any, default=None) – the topology of which this potential is a part ofmember_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 typeexpression(Optional[Union[str, sympy.Expr]], default=0.5 * k * ((phi - phi_eq))**2) – The mathematical expression of the functional form of the potentialparameters(Optional[dict], default=None) – The parameters of the Potential expression and their corresponding values, as unyt quantitiesindependent_variables(Optional[Union[set, str]], default=None) – The independent variables in the Potential’s expressionNotes

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

classmethod`construct`

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

`copy`

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

Parameters:

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

`dict`

¶

`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 objectparameters(dict,) – The parameters of the potential object to createtopology(gmso.Topology, default=None) – The topology to which the created potential object belongs toReturns: The potential object created

Return type: gmso.ParametricPotential

Raises:

`GMSOError`

– If potential_template is not of instance PotentialTemplate

`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().

`parameters`

¶

`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 unchangedparameters(dict) – {parameter: value} in the expression If None, the parameters remain unchangedNotes

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)[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.0Variables:

name(str) – Name of the forcefieldversion(str) – Version of the forcefieldatom_types(dict) – A collection of atom types in the forcefieldbond_types(dict) – A collection of bond types in the forcefieldangle_types(dict) – A collection of angle types in the forcefielddihedral_types(dict) – A collection of dihedral types in the forcefieldunits(dict) – A collection of unyt.Unit objects used in the forcefieldscaling_factors(dict) – A collection of scaling factors used in the forcefieldSee also

`gmso.ForceField.from_xml`

- A class method to create forcefield object from XML files

`atom_class_groups`

¶Return a dictionary of atomClasses in the Forcefield

classmethod`from_xml`

(xmls_or_etrees)[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 TreesReturns: forcefield– A gmso.Forcefield object with a collection of Potential objects created using the information in the XML fileReturn type: gmso.ForceField

`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