# GMSO

#### Purpose: To provide a general in-memory representation of chemical topologies for molecular simulation.

__Chemical topology:__ A system with which to perform molecular simulation. This includes, but is not limited to, particle coordinates, particle connectivity, box information, and force field data (functional forms, parameters tagged with units, partial charges, etc.).

## Scope

* Create and manipulate chemical topologies
* Write chemical topologies to file-based chemical topology representations used by various simulation engines
* Interconvert between many file-based chemical topology representations without information loss
* Specifically _do not_ support conversions between trajectory (i.e., output) file formats for analysis codes

## Approach

It is our goal to _assume no specific chemistries, models (i.e., interaction potentials), simulation engines, or existing file formats._

This will enable:

* Support for a variety of models in the molecular simulation/computational chemistry community: this includes atomistic models, united-atom/coarse-grained models, polarizable models, and more.
* More compatibility with new engines: by not designing for compatibility with any particular simulation engine or ecosystem, it becomes more tractable to add support for engines that are not currently supported.

# Core Classes

## Topology

A topology is a container for a chemical topology (see defintion above). A topology is the fundamental data structure in GMSO, from which we can gather various information about the chemical topology, apply or modify forceifled parameters, and interconvert between file-based chemical topology representations used by various simulation engines.

The `gmso.Topology` class should map as closely as possible to our definition of a chemical topology.

Therefore, the key items in a topology are:

* Sites
* Connections
* Box

A single topology is required to be contained within a box. There is nothing preventing a user from creating multiple topologies for multiple boxes.

Some other attributes of a topology include:

* Subtopologies
* Combining rule
* etc...

__Subtopologies__ should be a collection of sites. We should provide a method to create a new topology from a subtopology if desired. We will throw warnings if extracting a subtopology breaks bonds.

__Some comments on behavior:__

* Remove a site: Delete any connections involving that site

## Forcefield

A forcefield is a collection of Potential classes (`AtomTypes`, `BondTypes`, `DihedralTypes`, etc.) that may be referenced in a topology. There is no requirement for a 1-to-1 mapping between a `gmso.Topology` and `gmso.ForceField`.

## Site (abstract base class)

* Name
* Location

### Atom

* Element --> restricted to periodic table (object)?
* Mass --> inherited from `Element` (?)
* Charge --> if `None`, inherited from AtomType
* AtomType --> pointer to `gmso.ForceField.AtomType`

### Bead

* Mass
* Charge
* BeadType

### Virtual site

* Mass = 0
* Charge
* VirtualSiteType

## Connection (abstract base class)

* Connection members
* Connection type

### Bond

* 2 members
* BondType

### Angle

* 3 members
* AngleType

### Dihedral

* 4 members
* DihedralType