openforcefield.topology.Atom¶

class openforcefield.topology.Atom(atomic_number, formal_charge, is_aromatic, name=None, molecule=None, stereochemistry=None)[source]¶

A particle representing a chemical atom.

Note that non-chemical virtual sites are represented by the VirtualSite object.

Todo

Should Atom objects be immutable or mutable?
Do we want to support the addition of arbitrary additional properties, such as floating point quantities (e.g. charge), integral quantities (such as id or serial index in a PDB file), or string labels (such as Lennard-Jones types)?

Todo

Allow atoms to have associated properties.

Warning

This API is experimental and subject to change.

Attributes:

Attributes:	`atomic_number` The integer atomic number of the atom. `bonded_atoms` The list of `Atom` objects this atom is involved in bonds with `bonds` The list of `Bond` objects this atom is involved in. `element` The element name `formal_charge` The atom’s formal charge `is_aromatic` The atom’s is_aromatic flag `mass` The standard atomic weight (abundance-weighted isotopic mass) of the atomic site. `molecule` The `Molecule` this atom is part of. `molecule_atom_index` The index of this Atom within the the list of atoms in `Molecules`. `molecule_particle_index` The index of this Atom within the the list of particles in the parent `Molecule`. `name` The name of this atom, if any `partial_charge` The partial charge of the atom, if any. `stereochemistry` The atom’s stereochemistry (if defined, otherwise None) `virtual_sites` The list of `VirtualSite` objects this atom is involved in.

atomic_number: The integer atomic number of the atom.
bonded_atoms: The list of Atom objects this atom is involved in bonds with
bonds: The list of Bond objects this atom is involved in.
element: The element name
formal_charge: The atom’s formal charge
is_aromatic: The atom’s is_aromatic flag
mass: The standard atomic weight (abundance-weighted isotopic mass) of the atomic site.
molecule: The Molecule this atom is part of.
molecule_atom_index: The index of this Atom within the the list of atoms in Molecules.
molecule_particle_index: The index of this Atom within the the list of particles in the parent Molecule.
name: The name of this atom, if any
partial_charge: The partial charge of the atom, if any.
stereochemistry: The atom’s stereochemistry (if defined, otherwise None)
virtual_sites: The list of VirtualSite objects this atom is involved in.

Methods

`add_bond`(bond)	Adds a bond that this atom is involved in ..
`add_virtual_site`(vsite)	Adds a bond that this atom is involved in ..
`from_bson`(serialized)	Instantiate an object from a BSON serialized representation.
`from_dict`(atom_dict)	Create an Atom from a dict representation.
`from_json`(serialized)	Instantiate an object from a JSON serialized representation.
`from_messagepack`(serialized)	Instantiate an object from a MessagePack serialized representation.
`from_pickle`(serialized)	Instantiate an object from a pickle serialized representation.
`from_toml`(serialized)	Instantiate an object from a TOML serialized representation.
`from_xml`(serialized)	Instantiate an object from an XML serialized representation.
`from_yaml`(serialized)	Instantiate from a YAML serialized representation.
`is_bonded_to`(atom2)	Determine whether this atom is bound to another atom
`to_bson`()	Return a BSON serialized representation.
`to_dict`()	Return a dict representation of the atom.
`to_json`([indent])	Return a JSON serialized representation.
`to_messagepack`()	Return a MessagePack representation.
`to_pickle`()	Return a pickle serialized representation.
`to_toml`()	Return a TOML serialized representation.
`to_xml`([indent])	Return an XML representation.
`to_yaml`()	Return a YAML serialized representation.

__init__(atomic_number, formal_charge, is_aromatic, name=None, molecule=None, stereochemistry=None)[source]¶

Create an immutable Atom object.

Object is serializable and immutable.

Todo

Use attrs to validate?

Todo

We can add setters if we need to.

Parameters:

Parameters:	atomic_number : int Atomic number of the atom formal_charge : int Formal charge of the atom is_aromatic : bool If True, atom is aromatic; if False, not aromatic stereochemistry : str, optional, default=None Either ‘R’ or ‘S’ for specified stereochemistry, or None for ambiguous stereochemistry name : str, optional, default=None An optional name to be associated with the atom

atomic_number : int: Atomic number of the atom
formal_charge : int: Formal charge of the atom
is_aromatic : bool: If True, atom is aromatic; if False, not aromatic
stereochemistry : str, optional, default=None: Either ‘R’ or ‘S’ for specified stereochemistry, or None for ambiguous stereochemistry
name : str, optional, default=None: An optional name to be associated with the atom

Examples

Create a non-aromatic carbon atom

>>> atom = Atom(6, 0, False)

Create a chiral carbon atom

>>> atom = Atom(6, 0, False, stereochemistry='R', name='CT')

Methods

`__init__`(atomic_number, formal_charge, …)	Create an immutable Atom object.
`add_bond`(bond)	Adds a bond that this atom is involved in ..
`add_virtual_site`(vsite)	Adds a bond that this atom is involved in ..
`from_bson`(serialized)	Instantiate an object from a BSON serialized representation.
`from_dict`(atom_dict)	Create an Atom from a dict representation.
`from_json`(serialized)	Instantiate an object from a JSON serialized representation.
`from_messagepack`(serialized)	Instantiate an object from a MessagePack serialized representation.
`from_pickle`(serialized)	Instantiate an object from a pickle serialized representation.
`from_toml`(serialized)	Instantiate an object from a TOML serialized representation.
`from_xml`(serialized)	Instantiate an object from an XML serialized representation.
`from_yaml`(serialized)	Instantiate from a YAML serialized representation.
`is_bonded_to`(atom2)	Determine whether this atom is bound to another atom
`to_bson`()	Return a BSON serialized representation.
`to_dict`()	Return a dict representation of the atom.
`to_json`([indent])	Return a JSON serialized representation.
`to_messagepack`()	Return a MessagePack representation.
`to_pickle`()	Return a pickle serialized representation.
`to_toml`()	Return a TOML serialized representation.
`to_xml`([indent])	Return an XML representation.
`to_yaml`()	Return a YAML serialized representation.

Attributes

`atomic_number`	The integer atomic number of the atom.
`bonded_atoms`	The list of `Atom` objects this atom is involved in bonds with
`bonds`	The list of `Bond` objects this atom is involved in.
`element`	The element name
`formal_charge`	The atom’s formal charge
`is_aromatic`	The atom’s is_aromatic flag
`mass`	The standard atomic weight (abundance-weighted isotopic mass) of the atomic site.
`molecule`	The `Molecule` this atom is part of.
`molecule_atom_index`	The index of this Atom within the the list of atoms in `Molecules`.
`molecule_particle_index`	The index of this Atom within the the list of particles in the parent `Molecule`.
`name`	The name of this atom, if any
`partial_charge`	The partial charge of the atom, if any.
`stereochemistry`	The atom’s stereochemistry (if defined, otherwise None)
`virtual_sites`	The list of `VirtualSite` objects this atom is involved in.

add_bond(bond)[source]¶

Adds a bond that this atom is involved in .. todo :: Is this how we want to keep records?

Parameters:	bond: an openforcefield.topology.molecule.Bond A bond involving this atom

add_virtual_site(vsite)[source]¶

Adds a bond that this atom is involved in .. todo :: Is this how we want to keep records?

Parameters:	bond: an openforcefield.topology.molecule.Bond A bond involving this atom

to_dict()[source]¶: Return a dict representation of the atom.

classmethod from_dict(atom_dict)[source]¶: Create an Atom from a dict representation.

formal_charge¶: The atom’s formal charge

partial_charge¶

The partial charge of the atom, if any.

Returns:	float or None

is_aromatic¶: The atom’s is_aromatic flag

stereochemistry¶: The atom’s stereochemistry (if defined, otherwise None)

element¶: The element name

atomic_number¶: The integer atomic number of the atom.

mass¶

The standard atomic weight (abundance-weighted isotopic mass) of the atomic site.

Todo

Should we discriminate between standard atomic weight and most abundant isotopic mass?

TODO (from jeff): Are there atoms that have different chemical properties based on their isotopes?

name¶: The name of this atom, if any

bonds¶: The list of Bond objects this atom is involved in.

bonded_atoms¶: The list of Atom objects this atom is involved in bonds with

is_bonded_to(atom2)[source]¶

Determine whether this atom is bound to another atom

Parameters:	atom2: openforcefield.topology.molecule.Atom a different atom in the same molecule
Returns:	bool Whether this atom is bound to atom2

virtual_sites¶: The list of VirtualSite objects this atom is involved in.

molecule_atom_index¶: The index of this Atom within the the list of atoms in Molecules. Note that this can be different from molecule_particle_index.

molecule_particle_index¶: The index of this Atom within the the list of particles in the parent Molecule. Note that this can be different from molecule_atom_index.

classmethod from_bson(serialized)¶

Instantiate an object from a BSON serialized representation.

Specification: http://bsonspec.org/

Parameters:	serialized : bytes A BSON serialized representation of the object
Returns:	instance : cls An instantiated object

classmethod from_json(serialized)¶

Instantiate an object from a JSON serialized representation.

Specification: https://www.json.org/

Parameters:	serialized : str A JSON serialized representation of the object
Returns:	instance : cls An instantiated object

classmethod from_messagepack(serialized)¶

Instantiate an object from a MessagePack serialized representation.

Specification: https://msgpack.org/index.html

Parameters:	serialized : bytes A MessagePack-encoded bytes serialized representation
Returns:	instance : cls Instantiated object.

classmethod from_pickle(serialized)¶

Instantiate an object from a pickle serialized representation.

Warning

This is not recommended for safe, stable storage since the pickle specification may change between Python versions.

Parameters:	serialized : str A pickled representation of the object
Returns:	instance : cls An instantiated object

classmethod from_toml(serialized)¶

Instantiate an object from a TOML serialized representation.

Specification: https://github.com/toml-lang/toml

Parameters:	serlialized : str A TOML serialized representation of the object
Returns:	instance : cls An instantiated object

classmethod from_xml(serialized)¶

Instantiate an object from an XML serialized representation.

Specification: https://www.w3.org/XML/

Parameters:	serialized : bytes An XML serialized representation
Returns:	instance : cls Instantiated object.

classmethod from_yaml(serialized)¶

Instantiate from a YAML serialized representation.

Specification: http://yaml.org/

Parameters:	serialized : str A YAML serialized representation of the object
Returns:	instance : cls Instantiated object

molecule¶

The Molecule this atom is part of.

Todo

Should we have a single unique Molecule for each molecule type in the system,

or if we have multiple copies of the same molecule, should we have multiple ``Molecule``s?

to_bson()¶

Return a BSON serialized representation.

Specification: http://bsonspec.org/

Returns:	serialized : bytes A BSON serialized representation of the objecft

to_json(indent=None)¶

Return a JSON serialized representation.

Specification: https://www.json.org/

Parameters:	indent : int, optional, default=None If not None, will pretty-print with specified number of spaces for indentation
Returns:	serialized : str A JSON serialized representation of the object

to_messagepack()¶

Return a MessagePack representation.

Specification: https://msgpack.org/index.html

Returns:	serialized : bytes A MessagePack-encoded bytes serialized representation of the object

to_pickle()¶

Return a pickle serialized representation.

Warning

This is not recommended for safe, stable storage since the pickle specification may change between Python versions.

Returns:	serialized : str A pickled representation of the object

to_toml()¶

Return a TOML serialized representation.

Specification: https://github.com/toml-lang/toml

Returns:	serialized : str A TOML serialized representation of the object

to_xml(indent=2)¶

Return an XML representation.

Specification: https://www.w3.org/XML/

Parameters:	indent : int, optional, default=2 If not None, will pretty-print with specified number of spaces for indentation
Returns:	serialized : bytes A MessagePack-encoded bytes serialized representation.

to_yaml()¶

Return a YAML serialized representation.

Specification: http://yaml.org/

Returns:	serialized : str A YAML serialized representation of the object