Abstract Base Classes

The gmso.abc module defines the abstract base classes that underpin all data structures in GMSO. These classes are not meant to be instantiated directly; instead, they provide a shared interface and common behaviour that concrete classes (e.g., gmso.Atom, gmso.Bond) build upon.

GMSOBase

GMSOBase is the root Pydantic BaseModel that every GMSO object derives from. It enforces strict validation, forbids extra fields, and provides JSON-serialisation helpers.

class gmso.abc.gmso_base.GMSOBase(**data)

Bases: BaseModel, ABC

A BaseClass to all abstract classes in GMSO.

json_dict(**kwargs)

Return a JSON serializable dictionary from the object

classmethod validate(value)

Ensure that the object is validated before use.

Site

Site is the abstract base for all interaction sites (atoms, virtual sites, coarse-grained beads, etc.). It stores a 3-D Cartesian position, an optional name, and optional molecule/residue labels.

class gmso.abc.abstract_site.Site(**data)

Bases: GMSOBase

name_: str

label_: str

group_: Annotated[str, Strict(strict=True)] | None

molecule_: Molecule | list | tuple | None

residue_: Residue | list | tuple | None

position_: Sequence[float] | ndarray | unyt_array

property name: str

Return the name of the site.

property position: unyt_array

Return the 3D Cartesian coordinates of the site.

property label: str

Return the label assigned to the site.

property group: str

Return the group of the site.

property molecule: Molecule | None

Return the molecule label of the site.

property residue: Residue | None

Return the residue label of the site.

serialize_position(position_)

classmethod is_valid_position(position)

Validate attribute position.

classmethod parse_name(value)

classmethod parse_residue(value)

classmethod parse_molecule(value)

Molecule

A lightweight label that groups sites into named, numbered molecules.

class gmso.abc.abstract_site.Molecule(**data)

Bases: GMSOBase

name_: str

number_: int

isrigid_: bool

property name: str

Return the name of the molecule.

property number: int

Return the index/number of the moleucle.

property isrigid: bool

Return the rigid label of the molecule.

Residue

A lightweight label that groups sites into named, numbered residues.

class gmso.abc.abstract_site.Residue(**data)

Bases: GMSOBase

name_: str

number_: int

property name: str

Return the name of the residue.

property number: int

Return the index/number of the residue.

AbstractPotential

AbstractPotential is the abstract base for all potential-energy functions. It stores the functional form as a sympy expression and the parameters—with physical units—as a dictionary.

class gmso.abc.abstract_potential.AbstractPotential(name='Potential', expression='a*x+b', independent_variables=None, potential_expression=None, *, tags={})

Bases: GMSOBase

name_: str

potential_expression_: PotentialExpression

tags_: Dict[str, Any]

property name: str

The name of the potential.

property independent_variables: Set

The independent variables in the potential’s expression.

Returns the set of sympy symbols that are not parameters — typically the interparticle distance r or an angle theta.

property expression

The mathematical expression of the potential as a sympy.Expr.

property potential_expression: PotentialExpression

The PotentialExpression for this potential.

Bundles the sympy expression, the independent variables, and the parameter dictionary into a single validated object.

property tags: Dict[str, Any]

Arbitrary metadata attached to this potential.

property tag_names: List[str]

property tag_names_iter: Iterator[str]

serialize_expression(potential_expression_)

serialize_tags(tags_)

add_tag(tag, value, overwrite=True)

Add or update a metadata tag on this potential.

Parameters:

• tag (str) – Name of the tag to add.

• value (Any) – Value to associate with the tag.

• overwrite (bool) – If False, raise ValueError when tag already exists.

Return type:

None

get_tag(tag, throw=False)

Return the value of a metadata tag.

Parameters:

• tag (str) – Name of the tag to retrieve.

• throw (bool) – If True, raise KeyError when tag does not exist. If False, return None for missing tags.

Return type:

Any

delete_tag(tag)

Delete a metadata tag.

Parameters:

tag (str) – Name of the tag to delete.

Raises:

KeyError – If tag does not exist.

Return type:

None

pop_tag(tag)

Remove and return a metadata tag, or None if absent.

Parameters:

tag (str) – Name of the tag to pop.

Return type:

Any

classmethod validate_potential_expression(v)

Connection

Connection is the abstract base for all topological connections between sites (bonds, angles, dihedrals, impropers).

class gmso.abc.abstract_connection.Connection(**data)

Bases: GMSOBase

name_: str

connection_members_: Sequence[Site] | None

property connection_members: Sequence[Site] | None

Return the ordered sequence of sites that form this connection.

property name: str

Return the name of this connection.

property member_types: List[str] | None

Return the atom-type name of each connection member.

Returns the names from the connection’s connection_type when available, otherwise falls back to the individual members’ atom types. Returns None when no type information is present.

property member_classes: List[str] | None

Return the atom-type class of each connection member.

Returns the classes from the connection’s connection_type when available, otherwise falls back to the individual members’ atom types. Returns None when no type information is present.

classmethod validate_fields(values)

get_connection_identifiers()