GMSO: Flexible storage of chemical topology for molecular simulation
This is the documentation for GMSO
, the General Molecular Simulation Object.
It is a part of the MoSDeF, the Molecular Simulation
Design Framework.
Design Principles
Scope and Features of GMSO
GMSO
is designed to enable the flexible, general representation of
chemical topologies for molecular simulation. Efforts are made to enable
lossless, bias-free storage of data, without assuming particular chemistries,
models, or using any particular engine’s ecosystem as a starting point. The
scope is generally restrained to the preparation, manipulation, and conversion
of and of input files for molecular simulation, i.e. before engines are called
to execute the simulations themselves. GMSO
currently does not support
conversions between trajectory file formats for analysis codes. In the scope of
molecular simulation, we loosely define a chemical topology as everything
needed to reproducibly prepare a chemical system for simulation. This includes
particle coordinates and connectivity, box information, force field data
(functional forms, parameters tagged with units, partial charges, etc.) and
some optional information that may not apply to all systems (i.e. specification
of elements with each particle).
GMSO
enables the following features:
Supporting a variety of models in the molecular simulation/computational chemistry community: No assumptions are made about an interaction site representing an atom or bead, instead supported atomistic, united-atom/coarse-grained, polarizable, and other models!
Greater flexibility for exotic potentials: The
AtomType
(and analogue classes for intramolecular interactions) usessympy
to store any potential that can be represented by a mathematical expression. If you can write it down, it can be stored!Easier development for glue to new engines: by not being designed for compatibility with any particular molecular simulation engine or ecosystem, it becomes more tractable for developers in the community to add glue for engines that are not currently supported (and even ones that do not exist at present)!
Compatibility with existing community tools: No single molecular simulation tool will be a silver bullet, so
GMSO
includes functions to convert objects. These can be used in their own right to convert between objects in-memory and also to support conversion to file formats not natively supported at any given time. Currently supported conversions includeParmEd
,OpenMM
,mBuild
,MDTraj
, with others coming in the future!Native support for reading and writing many common file formats (
XYZ
,GRO
,TOP
,LAMMPSDATA
) and indirect support, through other libraries, for many more!
Structure of GMSO
There are three main modules within the Python package:
gmso.core
stores the classes that constitute the core data structures.gmso.formats
stores readers and writers for (on-disk) file formats.gmso.external
includes functions that convert core data structures between external libraries and their internal representation.
Data Structures in GMSO
Following data structures are available within GMSO.
Core Classes
A topology. |
|
A sub-topology i.e. topology within a topology. |
|
An atom represents a single element association in a topology. |
|
A 2-partner connection between sites. |
|
A 3-partner connection between Atoms. |
|
A 4-partner connection between sites. |
|
sA 4-partner connection between sites. |
|
A description of non-bonded interactions between sites. |
|
A descripton of the interaction between 2 bonded partners. |
|
A descripton of the interaction between 3 bonded partners. |
|
A descripton of the interaction between 4 bonded partners. |
|
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
pairpotential_types (tuple of gmso.PairPotentialType objects) – A collection of PairPotentialTypes 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
pairpotential_type_expressions (list of gmso.PairPotentialType.expression objects) – A collection of all the expression for the PairPotentialTypes 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
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
- property n_sites
Return the number of sites associated with the sub-topology.
- property name
Return the name of the sub-topology.
- property parent
Return the parent of the sub-topology.
- property sites
Return the sites associated with the sub-topology.
Atom
- class gmso.Atom(name="''", label="''", residue_number=None, residue_name=None, 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
residue_number (<class ‘pydantic.types.StrictInt’>, default=None) – Residue number for the atom
residue_name (StrictStr, default=None) – Residue label for 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:
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
- property atom_type: Optional[gmso.core.atom_type.AtomType]
Return the atom_type associated with the atom.
- property charge: Optional[unyt.array.unyt_quantity]
Return the charge of the atom.
- property element: Optional[gmso.core.element.Element]
Return the element associated with the atom.
- property mass: Optional[unyt.array.unyt_quantity]
Return the mass of the atom.
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.
- property bond_type
Return parameters of the potential type.
- property connection_type
Return parameters of the potential type.
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
- property angle_type
Return the angle type if the angle is parametrized.
- property connection_type
Return the angle type if the angle is parametrized.
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
Improper
- class gmso.Improper(name="''", connection_members=None, improper_type=None)[source]
sA 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 atom 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
- property connection_type
Return Potential object for this connection if it exists.
- equivalent_members()[source]
Get a set of the equivalent connection member tuples.
- Returns
A unique set of tuples of equivalent connection members
- Return type
Notes
For an improper:
i, j, k, l == i, k, j, l
where i, j, k, and l are the connection members.
- property improper_type
Return Potential object for this connection if it exists.
Potential Classes
AtomType
- class gmso.AtomType(name='AtomType', mass=unyt_quantity(0., 'g/mol'), charge=unyt_quantity(0., 'C'), expression=None, parameters=None, potential_expression=None, independent_variables=None, atomclass='', doi='', overrides=None, definition='', description='', tags=None, topology=None)[source]
A description of non-bonded interactions between sites.
- Parameters
name (str, default=’’) – The name of the potential. Defaults to class name
potential_expression (PotentialExpression, default=<PotentialExpression, expression: a*x + b, 1 independent variables>) – The mathematical expression for the potential
tags (Any, default={}) – Tags associated with the potential
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=None) – 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.
- property atomclass
Return the atomclass of the atom_type.
- property charge
Return the charge of the atom_type.
- property definition
Return the SMARTS string of the atom_type.
- property description
Return the description of the atom_type.
- property doi
Return the doi of the atom_type.
- property mass
Return the mass of the atom_type.
- property overrides
Return the overrides of the atom_type.
BondType
- class gmso.BondType(name='BondType', expression=None, parameters=None, independent_variables=None, potential_expression=None, member_types=None, member_classes=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
name (str, default=’’) – The name of the potential. Defaults to class name
potential_expression (PotentialExpression, default=<PotentialExpression, expression: a*x + b, 1 independent variables>) – The mathematical expression for the potential
tags (Any, default={}) – Tags associated with the potential
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 defining the members of this bond type
member_classes (Tuple[str, str], default=None) – List-like of of gmso.AtomType.atomclass defining the members of this bond type
expression (Optional[Union[str, sympy.Expr]], default=None) – 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
- property member_types
Return the members involved in this bondtype.
AngleType
- class gmso.AngleType(name='AngleType', expression=None, parameters=None, independent_variables=None, potential_expression=None, member_types=None, member_classes=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
name (str, default=’’) – The name of the potential. Defaults to class name
potential_expression (PotentialExpression, default=<PotentialExpression, expression: a*x + b, 1 independent variables>) – The mathematical expression for the potential
tags (Any, default={}) – Tags associated with the potential
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 defining the members of this angle type
member_classes (Tuple[str, str, str], default=None) – List-like of gmso.AtomType.atomclass defining the members of this angle type
expression (Optional[Union[str, sympy.Expr]], default=None) – 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
DihedralType
- class gmso.DihedralType(name='DihedralType', expression=None, parameters=None, independent_variables=None, potential_expression=None, member_types=None, member_classes=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
name (str, default=’’) – The name of the potential. Defaults to class name
potential_expression (PotentialExpression, default=<PotentialExpression, expression: a*x + b, 1 independent variables>) – The mathematical expression for the potential
tags (Any, default={}) – Tags associated with the potential
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 defining the members of this dihedral type
member_classes (Tuple[str, str, str, str], default=None) – List-like of of gmso.AtomType.atomclass defining the members of this dihedral type
expression (Optional[Union[str, sympy.Expr]], default=None) – 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
ImproperType
- class gmso.ImproperType(name='ImproperType', expression=None, parameters=None, independent_variables=None, potential_expression=None, member_types=None, member_classes=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
name (str, default=’’) – The name of the potential. Defaults to class name
potential_expression (PotentialExpression, default=<PotentialExpression, expression: a*x + b, 1 independent variables>) – The mathematical expression for the potential
tags (Any, default={}) – Tags associated with the potential
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 gmso.AtomType.name defining the members of this improper type
member_classes (Tuple[str, str, str, str], default=None) – List-like of gmso.AtomType.atomclass defining the members of this improper type
expression (Optional[Union[str, sympy.Expr]], default=None) – 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
- property member_types
Return member information for this ImproperType.
PairPotentialType
- class gmso.PairPotentialType(name='PairPotentialType', expression=None, parameters=None, independent_variables=None, potential_expression=None, member_types=None, topology=None, tags=None)[source]
A description of custom pairwise potential between 2 AtomTypes that does not follow combination rule.
This is a subclass of the gmso.core.ParametricPotential superclass. PairPotentialType represents a type of pairwise potential between two Atomtypes that does not follow a specific combination rule, and includes the functional form describing its interactions. The functional form of the potential is stored as a sympy expression and the parameters, with units, are stored explicitly. The AtomTypes that are used to define the dihedral type are stored as member_types.
- Parameters
name (str, default=’’) – The name of the potential. Defaults to class name
potential_expression (PotentialExpression, default=<PotentialExpression, expression: a*x + b, 1 independent variables>) – The mathematical expression for the potential
tags (Any, default={}) – Tags associated with the potential
topology (Any, default=None) – the topology of which this potential is a part of
member_types (Tuple[str, str], default=None) – List-like of strs, referring to gmso.Atomtype.name or gmso.Atomtype.atomclass, defining the members of this pair potential type
expression (Optional[Union[str, sympy.Expr]], default=None) – 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
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
- property 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 ForceField object from the reference XML file. This method takes in a single or collection of XML files with information about gmso.AtomTypes, gmso.BondTypes, gmso.AngleTypes , gmso.PairPotentialTypes and gmso.DihedralTypes to create the ForceField object.
- Parameters
xmls_or_etrees (Union[str, Iterable[str], etree._ElementTree, Iterable[etree._ElementTree]]) – The forcefield XML locations or XML Element Trees
strict (bool, default=True) – If true, perform a strict validation of the forcefield XML file
greedy (bool, default=True) – If True, when using strict mode, fail on the first error/mismatch
- Returns
forcefield – A gmso.Forcefield object with a collection of Potential objects created using the information in the XML file
- Return type
- get_parameters(group, key, warn=False, copy=False)[source]
Return parameters for a specific potential by key in this ForceField.
This function uses the get_potential function to get Parameters
See also
gmso.ForceField.get_potential
Get specific potential/parameters from a forcefield potential group by key
- get_potential(group, key, warn=False)[source]
Return a specific potential by key in this ForceField.
- Parameters
group ({‘atom_type’, ‘bond_type’, ‘angle_type’, ‘dihedral_type’, ‘improper_type’}) – The potential group to perform this search on
key (str (for atom type) or list of str (for connection types)) – The key to lookup for this potential group
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
- 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
- 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
- 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
- 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
- group_pairpotential_types_by_expression()[source]
Return all PairPotentialTypes in this ForceField with grouped by expression
See also
_group_by_expression
Groups a dictionary of gmso.ParametricPotentials by their expression
- Returns
A dictionary where the key, value -> expression, list of PairPotentialTypes with that expression
- Return type
Formats
This submodule provides readers and writers for (on-disk) file formats.
GROMACS
The following methods are available for reading and writing GROMACS files.
- gmso.formats.read_gro(filename)[source]
Create a topology from a provided gro file.
The Gromos87 (gro) format is a common plain text structure file used commonly with the GROMACS simulation engine. This file contains the simulation box parameters, number of atoms, the residue and atom number for each atom, as well as their positions and velocities (velocity is optional). This method will receive a filepath representation either as a string, or a file object and return a topology.
- Parameters
filename (str or file object) – The path to the gro file either as a string, or a file object that points to the gro file.
- Returns
A topology object containing site information
- Return type
gmso.core.topology
Notes
Gro files do not specify connections between atoms, the returned topology will not have connections between sites either.
Currently this implementation does not support a gro file with more than 1 frame.
All residues and resid information from the gro file are currently lost when converting to topology.
- gmso.formats.write_gro(top, filename)[source]
Write a topology to a gro file.
The Gromos87 (gro) format is a common plain text structure file used commonly with the GROMACS simulation engine. This file contains the simulation box parameters, number of atoms, the residue and atom number for each atom, as well as their positions and velocities (velocity is optional). This method takes a topology object and a filepath string or file object and saves a Gromos87 (gro) to disk.
- Parameters
top (gmso.core.topology) – The topology to write out to the gro file.
filename (str or file object) – The location and name of file to save to disk.
Notes
Multiple residue assignment has not been added, each site will belong to the same resid of 1 currently.
Velocities are not written out.
GSD
The following methods are available for reading and writing GSD files.
- gmso.formats.write_gsd(top, filename, ref_distance=unyt_quantity(1., 'nm'), ref_mass=unyt_quantity(1., 'g/mol'), ref_energy=unyt_quantity(1., 'kcal/mol'), rigid_bodies=None, shift_coords=True, write_special_pairs=True)[source]
Output a GSD file (HOOMD v2 default data format).
The GSD binary file format is the native format of HOOMD-Blue. This file can be used as a starting point for a HOOMD-Blue simulation, for analysis, and for visualization in various tools.
- Parameters
top (gmso.Topology) – gmso.Topology object
filename (str) – Path of the output file.
ref_distance (float, optional, default=1.0) – Reference distance for conversion to reduced units
ref_mass (float, optional, default=1.0) – Reference mass for conversion to reduced units
ref_energy (float, optional, default=1.0) – Reference energy for conversion to reduced units
rigid_bodies (list of int, optional, default=None) – List of rigid body information. An integer value is required for each atom corresponding to the index of the rigid body the particle is to be associated with. A value of None indicates the atom is not part of a rigid body.
shift_coords (bool, optional, default=True) – Shift coordinates from (0, L) to (-L/2, L/2) if necessary.
write_special_pairs (bool, optional, default=True) – Writes out special pair information necessary to correctly use the OPLS fudged 1,4 interactions in HOOMD.
Notes
Force field parameters are not written to the GSD file and must be included manually in a HOOMD input script. Work on a HOOMD plugin is underway to read force field parameters from a Foyer XML file.
xyz
The following methods are available for reading and writing xyz files.
LAMMPS DATA
The following methods are available for reading and writing LAMMPS data.
- gmso.formats.write_lammpsdata(topology, filename, atom_style='full')[source]
Output a LAMMPS data file.
Outputs a LAMMPS data file in the ‘full’ atom style format. Assumes use of ‘real’ units. See http://lammps.sandia.gov/doc/atom_style.html for more information on atom styles.
- Parameters
Topology (Topology) – A Topology Object
filename (str) – Path of the output file
atom_style (str, optional, default=’full’) – Defines the style of atoms to be saved in a LAMMPS data file. The following atom styles are currently supported: ‘full’, ‘atomic’, ‘charge’, ‘molecular’ see http://lammps.sandia.gov/doc/atom_style.html for more information on atom styles.
Notes
See http://lammps.sandia.gov/doc/2001/data_format.html for a full description of the LAMMPS data format. This is a work in progress, as only atoms, masses, and atom_type information can be written out.
Some of this function has been adopted from mdtraj’s support of the LAMMPSTRJ trajectory format. See https://github.com/mdtraj/mdtraj/blob/master/mdtraj/formats/lammpstrj.py for details.
External
This submodule includes functions that convert core data structures between external libraries and their internal representation.
mBuild
The following methods are available for converting mBuild objects to and from GMSO
.
- gmso.external.from_mbuild(compound, box=None, search_method=<function element_by_symbol>)[source]
Convert an mbuild.Compound to a gmso.Topology.
This conversion makes the following assumptions about the inputted Compound:
All positional and box dimension values in compound are in nanometers.
If the Compound has 4 or more levels of hierarchy, these are compressed to 3 levels of hierarchy in the resulting Topology. The top level Compound becomes the Topology, the second level Compounds become SubTopologies, and each particle becomes a Site, which are added to their corresponding SubTopologies.
Furthermore, Sites that do not belong to a sub-Compound are added to a single-Site SubTopology.
The box dimension are extracted from compound.periodicity. If the compound.periodicity is None, the box lengths are the lengths of the bounding box + a 0.5 nm buffer.
Only Bonds are added for each bond in the Compound. If Angles and Dihedrals are desired in the resulting Topology, they must be added separately from this function.
- Parameters
compound (mbuild.Compound) – mbuild.Compound instance that need to be converted
box (mbuild.Box, optional, default=None) – Box information to be loaded to a gmso.Topology
search_method (function, optional, default=element_by_symbol) – Searching method used to assign element from periodic table to particle site. The information specified in the search_method argument is extracted from each Particle’s name attribute. Valid functions are element_by_symbol, element_by_name, element_by_atomic_number, and element_by_mass, which can be imported from `gmso.core.element’
- Returns
top
- Return type
Parmed
Conversion methods for Parmed objects to and from GMSO
.
- gmso.external.from_parmed(structure, refer_type=True)[source]
Convert a parmed.Structure to a gmso.Topology.
Convert a parametrized or un-parametrized parmed.Structure object to a topology.Topology. Specifically, this method maps Structure to Topology and Atom to Site. At this point, this method can only convert AtomType, BondType and AngleType. Conversion of DihedralType will be implement in the near future.
- Parameters
structure (parmed.Structure) – parmed.Structure instance that need to be converted.
refer_type (bool, optional, default=True) – Whether or not to transfer AtomType, BondType, AngleType, and DihedralType information
- Returns
top
- Return type
OpenMM
Conversion methods for OpenMM objects to and from GMSO
.
- gmso.external.to_openmm(topology, openmm_object='topology')[source]
Convert an untyped topology object to an untyped OpenMM modeller or topology.
This is useful if it’s preferred to atom-type a system within OpenMM. See http://openmm.org for more information.
- Parameters
topology (Topology object) – An untyped topology object
open_mm_object (‘topology’ or ‘modeller’ OpenMM object, default=’topology’) – Untyped OpenMM object to convert to
- Returns
open_mm_object
- Return type
Untyped topology or modeller object
Installation
Installing with conda
Starting from GMSO
version 0.3.0
, you can use conda to install GMSO
in your preferred environment. This will also install the dependencies of GMSO
.
(your-env) $ conda install -c conda-forge gmso
Installing from source conda
Dependencies of GMSO are listed in the files environment.yml
(lightweight environment specification containing minimal dependencies) and environment-dev.yml
(comprehensive environment specification including optional and testing packages for developers).
The gmso
or gmso-dev
conda environments can be created with
$ git clone https://github.com/mosdef-hub/gmso.git
$ cd gmso
# for gmso conda environment
$ conda env create -f environment.yml
$ conda activate gmso
# for gmso-dev
$ conda env create -f environment-dev.yml
$ conda activate gmso
# install a non-editable version of gmso
$ pip install .
Install an editable version from source
Once all dependencies have been installed and the conda
environment has been created, the GMSO
itself can be installed.
$ cd gmso
$ conda activate gmso-dev # or gmso depending on your installation
$ pip install -e .
Supported Python Versions
Python 3.7 is the recommend version for users. It is the only version on which development and testing consistently takes place. Older (3.6) and newer (3.8+) versions of Python 3 are likely to work but no guarantee is made and, in addition, some dependencies may not be available for other versions. No effort is made to support Python 2 because it is considered obsolete as of early 2020.
Testing your installation
GMSO
uses py.test
to execute its unit tests. To run them, first install the gmso-dev
environment from above as well as gmso
itself
$ conda activate gmso-dev
$ pip install -e .
And then run the tests with the py.test
executable:
$ py.test -v
Install pre-commit
We use [pre-commit](https://pre-commit.com/) to automatically handle our code formatting and this package is included in the dev environment.
With the gmso-dev
conda environment active, pre-commit can be installed locally as a git hook by running
$ pre-commit install
And (optional) all files can be checked by running
$ pre-commit run --all-files
Building the documentation
GMSO
uses sphinx to build its documentation. To build the docs locally, run the following while in the docs
directory:
$ conda env create -f docs-env.yml
$ conda activate gmso-docs
$ make html
Using GMSO with Docker
As much of scientific software development happens in unix platforms, to avoid the quirks of development dependent on system you use, a recommended way is to use docker or other containerization technologies. This section is a how to guide on using GMSO
with docker.
Prerequisites
A docker installation in your machine. Follow this link to get a docker installation working on your machine. If you are not familiar with docker and want to get started with docker, the Internet is full of good tutorials like the ones here and here.
Quick Start
After you have a working docker installation, please use the following command to use run a jupyter-notebook with all the dependencies for GMSO installed:
$ docker pull mosdef/gmso:latest
$ docker run -it --name gmso -p 8888:8888 mosdef/gmso:latest
If no command is provided to the container (as above), the container starts a jupyter-notebook
at the (container) location
/home/anaconda/data
.
To access the notebook, paste the notebook URL into a web browser on your computer. When you are finished, you can control-C to
exit the notebook as usual. The docker container will exit upon notebook shutdown.
Alternatively, you can also start a Bourne shell to use python from the container’s terminal:
$ docker run -it --mount type=bind,source=$(pwd),target="/home/anaconda/data" mosdef/gmso:latest sh
~ $ source .profile
(gmso-dev) ~ $
Warning
Containers by nature are ephemeral, so filesystem changes (e.g., adding a new notebook) only persist until the end of the container’s lifecycle. If the container is removed, any changes or code additions will not persist. See the section below for persistent data.
Note
The -it flags connect your keyboard to the terminal running in the container.
You may run the prior command without those flags, but be aware that the container will not respond to any keyboard input.
In that case, you would need to use the docker ps
and docker kill
commands to shut down the container.
Persisting User Volumes
If you will be using GMSO from a docker container, a recommended way is to mount what are called user volumes in the container. User volumes will provide a way to persist all filesystem/code additions made to a container regardless of the container lifecycle. For example, you might want to create a directory called gmso-notebooks in your local system, which will store all your GMSO notebooks/code. In order to make that accessible to the container(where the notebooks will be created/edited), use the following steps:
$ mkdir -p /path/to/gmso-notebooks
$ cd /path/to/gmso-notebooks
$ docker run -it --name gmso --mount type=bind,source=$(pwd),target=/home/anaconda/data -p 8888:8888 mosdef/gmso:latest
You can easily mount a different directory from your local machine by changing source=$(pwd)
to
source=/path/to/my/favorite/directory
.
Note
The --mount
flag mounts a volume into the docker container. Here we
use a bind
mount to bind the current directory on our local filesystem
to the /home/anaconda/data
location in the container. The files you see
in the jupyter-notebook
browser window are those that exist on your
local machine.
Warning
If you are using the container with jupyter notebooks you should use
the /home/anaconda/data
location as the mount point inside the container;
this is the default notebook directory.
Running Python scripts in the container
Jupyter notebooks are a great way to explore new software and prototype
code. However, when it comes time for production science, it is often
better to work with python scripts. In order to execute a python script
(example.py
) that exists in the current working directory of your
local machine, run:
$ docker run --mount type=bind,source=$(pwd),target=/home/anaconda/data mosdef/gmso:latest "python data/test.py"
Note that once again we are bind
mounting the current working directory
to /home/anaconda/data
. The command we pass to the container is
python data/test.py
. Note the prefix data/
to the script; this is because
we enter the container in the home folder (/home/anaconda
), but our script
is located under /home/anaconda/data
.
Warning
Do not bind mount to target=/home/anaconda
. This will cause errors.
If you don’t require a Jupyter notebook, but just want a Python interpreter, you can run:
$ docker run --mount type=bind,source=$(pwd),target=/home/anaconda/data mosdef/gmso:latest python
If you don’t need access to any local data, you can of course drop the
--mount
command:
$ docker run mosdef/gmso:latest python
Cleaning Up
You can remove the created container by using the following command:
$ docker container rm gmso
Note
Instead of using latest, you can use the image mosdef/gmso:stable
for most recent stable release of GMSO
and run the tutorials.
Contributing
Contributions are welcomed via pull requests on GitHub. Developers and/or users will review requested changes and make comments. The rest of this file will serve as a set of general guidelines for contributors.
Features
Implement functionality in a general and flexible fashion
GMSO is designed to be general and flexible, not limited to single chemistries, file formats, simulation engines, or simulation methods. Additions to core features should attempt to provide something that is applicable to a variety of use-cases and not targeted at only the focus area of your research. However, some specific features targeted toward a limited use case may be appropriate. Speak to the developers before writing your code and they will help you make design choices that allow flexibility.
Version control
We currently use the “standard” Pull Request model. Contributions should be implemented on feature branches of forks. Please try to keep the master branch of your fork up-to-date with the master branch of the main repository.
Source code
Use a consistent style
It is important to have a consistent style throughout the source code. The following criteria are desired:
Lines wrapped to 80 characters
Lines are indented with spaces
Lines do not end with whitespace
For other details, refer to PEP8
To help with the above, there are tools such as flake8 and Black.
Document code with comments
All public-facing functions should have docstrings using the numpy style. This includes concise paragraph-style description of what the class or function does, relevant limitations and known issues, and descriptions of arguments. Internal functions can have simple one-liner docstrings.
Tests
Write unit tests
All new functionality in GMSO should be tested with automatic unit tests that execute in a few seconds. These tests should attempt to cover all options that the user can select. All or most of the added lines of source code should be covered by unit test(s). We currently use pytest, which can be executed simply by calling pytest from the root directory of the package.