RDKit::Atom Class Reference

The class for representing atoms. More...

#include <Atom.h>

Inheritance diagram for RDKit::Atom:

Public Types
enum	HybridizationType { UNSPECIFIED = 0, S, SP, SP2, SP3, SP3D, SP3D2, OTHER }
	store hybridization More...
enum	ChiralType { CHI_UNSPECIFIED = 0, CHI_TETRAHEDRAL_CW, CHI_TETRAHEDRAL_CCW, CHI_OTHER }
	store type of chirality More...
typedef boost::shared_ptr< Atom >	ATOM_SPTR
typedef boost::shared_ptr < const Atom >	C_ATOM_SPTR
typedef Queries::Query< int, Atom const *, true >	QUERYATOM_QUERY
Public Member Functions
	Atom ()
	Atom (unsigned int num)
	construct an Atom with a particular atomic number
	Atom (std::string what)
	construct an Atom with a particular symbol (looked up in the PeriodicTable)
	Atom (const Atom &other)
virtual	~Atom ()
virtual Atom *	copy () const
	makes a copy of this Atom and returns a pointer to it.
const int	getAtomicNum () const
	returns our atomic number
void	setAtomicNum (int newNum)
	sets our atomic number
std::string	getSymbol () const
	returns our symbol (determined by our atomic number)
ROMol &	getOwningMol () const
	returns a reference to the ROMol that owns this Atom
const unsigned int	getIdx () const
	returns our index within the ROMol
void	setIdx (unsigned int index)
	sets our index within the ROMol
unsigned int	getDegree () const
unsigned int	getTotalDegree () const
unsigned int	getTotalNumHs (bool includeNeighbors=false) const
	returns the total number of Hs (implicit and explicit) that this Atom is bound to
unsigned int	getNumImplicitHs () const
	returns the number of implicit Hs this Atom is bound to
int	getExplicitValence () const
	returns the number of explicit Hs this Atom is bound to
int	getImplicitValence () const
	returns the implicit valence for this Atom
unsigned int	getNumRadicalElectrons () const
	returns the number of radical electrons for this Atom
void	setNumRadicalElectrons (unsigned int num)
const int	getFormalCharge () const
	returns the formal charge of this atom
void	setFormalCharge (int what)
	set's the formal charge of this atom
void	setNoImplicit (bool what)
	sets our `noImplicit` flag, indicating whether or not we are allowed to have implicit Hs
bool	getNoImplicit () const
	returns the `noImplicit` flag
void	setNumExplicitHs (unsigned int what)
	sets our number of explict Hs
unsigned int	getNumExplicitHs () const
	returns our number of explict Hs
void	setIsAromatic (bool what)
	sets our `isAromatic` flag, indicating whether or not we are aromatic
bool	getIsAromatic () const
	returns our `isAromatic` flag
void	setMass (double what)
	sets our mass (for isotopes)
double	getMass () const
	returns our mass
void	setDativeFlag (int what)
	sets our `dativeFlag`
int	getDativeFlag () const
	returns our `dativeFlag`
bool	hasDativeFlag (int what) const
void	clearDativeFlag ()
	clears our `dativeFlag`
void	setChiralTag (ChiralType what)
	sets our `chiralTag`
void	invertChirality ()
	inverts our `chiralTag`
ChiralType	getChiralTag () const
	returns our `chiralTag`
void	setHybridization (HybridizationType what)
	sets our hybridization
HybridizationType	getHybridization () const
	returns our hybridization
virtual bool	hasQuery () const
virtual void	setQuery (QUERYATOM_QUERY *what)
	NOT CALLABLE.
virtual QUERYATOM_QUERY *	getQuery () const
	NOT CALLABLE.
virtual void	expandQuery (QUERYATOM_QUERY *what, Queries::CompositeQueryType how=Queries::COMPOSITE_AND, bool maintainOrder=true)
	NOT CALLABLE.
virtual bool	Match (Atom const *what) const
	returns whether or not we match the argument
virtual bool	Match (const ATOM_SPTR what) const
STR_VECT	getPropList () const
	returns a list with the names of our `properties`
template<typename T >
void	setProp (const char *key, T val, bool computed=false) const
	sets a `property` value
template<typename T >
void	setProp (const std::string key, T val, bool computed=false) const
template<typename T >
void	getProp (const char *key, T &res) const
	allows retrieval of a particular property value
template<typename T >
void	getProp (const std::string key, T &res) const
bool	hasProp (const char *key) const
	returns whether or not we have a `property` with name `key`
bool	hasProp (const std::string key) const
void	clearProp (const char *key) const
	clears the value of a `property`
void	clearProp (const std::string key) const
void	clearComputedProps () const
	clears all of our `computed` `properties`
int	getPerturbationOrder (INT_LIST probe) const
	returns the perturbation order for a list of integers
void	updatePropertyCache (bool strict=true)
	calculates any of our lazy `properties`
int	calcExplicitValence (bool strict=true)
	calculates and returns our explicit valence
int	calcImplicitValence (bool strict=true)
	calculates and returns our implicit valence
Protected Member Functions
void	setOwningMol (ROMol *other)
	sets our owning molecule
void	setOwningMol (ROMol &other)
	sets our owning molecule
void	initAtom ()
Protected Attributes
bool	df_isAromatic
bool	df_noImplicit
int	d_dativeFlag
unsigned int	d_numExplicitHs
int	d_formalCharge
unsigned int	d_atomicNum
unsigned int	d_index
int	d_implicitValence
int	d_explicitValence
unsigned int	d_numRadicalElectrons
ChiralType	d_chiralTag
HybridizationType	d_hybrid
double	d_mass
ROMol *	dp_mol
Dict *	dp_props
Friends
class	MolPickler
	the pickler needs access to our privates
class	ROMol
class	RWMol

Detailed Description

The class for representing atoms.

Notes:

many of the methods of Atom require that the Atom be associated with a molecule (an ROMol).
each Atom maintains a Dict of properties:
- Each property is keyed by name and can store an arbitrary type.
- Properties can be marked as calculated, in which case they will be cleared when the clearComputedProps() method is called.
- Because they have no impact upon chemistry, all property operations are const, this allows extra flexibility for clients who need to store extra data on Atom objects.
Atom objects are lazy about computing their explicit and implicit valence values. These will not be computed until their values are requested.

Chirality:

The chirality of an Atom is determined by two things:

its chiralTag
the input order of its bonds (see note below for handling of implicit Hs)

For tetrahedral coordination, the chiralTag tells you what direction you have to rotate to get from bond 2 to bond 3 while looking down bond 1. This is pretty much identical to the SMILES representation of chirality.

NOTE: if an atom has an implicit H, the bond to that H is considered to be at the *end* of the list of other bonds.

Definition at line 59 of file Atom.h.

Member Typedef Documentation

typedef boost::shared_ptr<Atom> RDKit::Atom::ATOM_SPTR

Definition at line 65 of file Atom.h.

typedef boost::shared_ptr<const Atom> RDKit::Atom::C_ATOM_SPTR

Definition at line 66 of file Atom.h.

typedef Queries::Query<int,Atom const *,true> RDKit::Atom::QUERYATOM_QUERY

Reimplemented in RDKit::QueryAtom.

Definition at line 68 of file Atom.h.

Member Enumeration Documentation

enum RDKit::Atom::ChiralType

store type of chirality

Enumerator:

CHI_UNSPECIFIED	chirality that hasn't been specified
CHI_TETRAHEDRAL_CW	tetrahedral: clockwise rotation (SMILES @)
CHI_TETRAHEDRAL_CCW	tetrahedral: counter-clockwise rotation (SMILES @)
CHI_OTHER	some unrecognized type of chirality

Definition at line 83 of file Atom.h.

enum RDKit::Atom::HybridizationType

store hybridization

Enumerator:

UNSPECIFIED	hybridization that hasn't been specified
S
SP
SP2
SP3
SP3D
SP3D2
OTHER	unrecognized hybridization

Definition at line 71 of file Atom.h.

Constructor & Destructor Documentation

RDKit::Atom::Atom ( )

RDKit::Atom::Atom ( unsigned int num ) [explicit]

construct an Atom with a particular atomic number

RDKit::Atom::Atom ( std::string what ) [explicit]

construct an Atom with a particular symbol (looked up in the PeriodicTable)

RDKit::Atom::Atom ( const Atom & other )

virtual RDKit::Atom::~Atom ( ) [virtual]

Member Function Documentation

int RDKit::Atom::calcExplicitValence ( bool strict = true )

calculates and returns our explicit valence

Notes:

requires an owning molecule

int RDKit::Atom::calcImplicitValence ( bool strict = true )

calculates and returns our implicit valence

Notes:

requires an owning molecule

void RDKit::Atom::clearComputedProps ( ) const [inline]

clears all of our computed properties

Definition at line 373 of file Atom.h.

References RDKit::Dict::clearVal(), dp_props, getProp(), hasProp(), and RDKit::Dict::setVal().

void RDKit::Atom::clearDativeFlag ( ) [inline]

clears our dativeFlag

Definition at line 217 of file Atom.h.

References d_dativeFlag.

void RDKit::Atom::clearProp ( const std::string key ) const [inline]

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Definition at line 359 of file Atom.h.

void RDKit::Atom::clearProp ( const char * key ) const [inline]

clears the value of a property

Notes:

if no property with name key exists, a KeyErrorException will be thrown.
if the property is marked as computed, it will also be removed from our list of computedProperties

Definition at line 354 of file Atom.h.

virtual Atom* RDKit::Atom::copy ( ) const [virtual]

makes a copy of this Atom and returns a pointer to it.

Note: the caller is responsible for deleteing the result

Reimplemented in RDKit::QueryAtom.

virtual void RDKit::Atom::expandQuery	(	QUERYATOM_QUERY *	what,
		Queries::CompositeQueryType	how = `Queries::COMPOSITE_AND`,
		bool	maintainOrder = `true`
	)			`[virtual]`

NOT CALLABLE.

Reimplemented in RDKit::QueryAtom.

const int RDKit::Atom::getAtomicNum ( ) const [inline]

returns our atomic number

Definition at line 105 of file Atom.h.

Referenced by RDKit::queryAtomNum().

ChiralType RDKit::Atom::getChiralTag ( ) const [inline]

returns our chiralTag

Definition at line 224 of file Atom.h.

int RDKit::Atom::getDativeFlag ( ) const [inline]

returns our dativeFlag

Definition at line 209 of file Atom.h.

unsigned int RDKit::Atom::getDegree ( ) const

returns the explicit degree of the Atom (number of bonded neighbors in the graph)

Notes:

requires an owning molecule

Referenced by RDKit::queryAtomExplicitDegree(), and RDKit::queryAtomUnsaturated().

int RDKit::Atom::getExplicitValence ( ) const

returns the number of explicit Hs this Atom is bound to

Referenced by RDKit::queryAtomExplicitValence(), RDKit::queryAtomTotalValence(), and RDKit::queryAtomUnsaturated().

const int RDKit::Atom::getFormalCharge ( ) const [inline]

returns the formal charge of this atom

Definition at line 176 of file Atom.h.

Referenced by RDKit::queryAtomFormalCharge().

HybridizationType RDKit::Atom::getHybridization ( ) const [inline]

returns our hybridization

Definition at line 229 of file Atom.h.

References d_hybrid.

Referenced by RDKit::queryAtomHybridization().

const unsigned int RDKit::Atom::getIdx ( ) const [inline]

returns our index within the ROMol

Definition at line 116 of file Atom.h.

References d_index.

Referenced by RDKit::SLNParse::addAtomToMol(), RDKit::RecursiveStructureQuery::getAtIdx(), RDKit::queryAtomIsInRingOfSize(), RDKit::queryAtomMinRingSize(), RDKit::queryAtomRingMembership(), RDKit::queryIsAtomInNRings(), and RDKit::queryIsAtomInRing().

int RDKit::Atom::getImplicitValence ( ) const

returns the implicit valence for this Atom

Notes:

requires an owning molecule

Referenced by RDKit::queryAtomImplicitValence(), and RDKit::queryAtomTotalValence().

bool RDKit::Atom::getIsAromatic ( ) const [inline]

returns our isAromatic flag

Definition at line 194 of file Atom.h.

References df_isAromatic.

Referenced by RDKit::queryAtomAliphatic(), and RDKit::queryAtomAromatic().

double RDKit::Atom::getMass ( ) const [inline]

returns our mass

Definition at line 199 of file Atom.h.

References d_mass.

Referenced by RDKit::queryAtomMass().

bool RDKit::Atom::getNoImplicit ( ) const [inline]

returns the noImplicit flag

Definition at line 184 of file Atom.h.

References df_noImplicit.

unsigned int RDKit::Atom::getNumExplicitHs ( ) const [inline]

returns our number of explict Hs

Definition at line 189 of file Atom.h.

References d_numExplicitHs.

Referenced by RDKit::queryAtomExplicitValence().

unsigned int RDKit::Atom::getNumImplicitHs ( ) const

returns the number of implicit Hs this Atom is bound to

Notes:

requires an owning molecule

unsigned int RDKit::Atom::getNumRadicalElectrons ( ) const [inline]

returns the number of radical electrons for this Atom

Notes:

requires an owning molecule

Definition at line 171 of file Atom.h.

ROMol& RDKit::Atom::getOwningMol ( ) const [inline]

returns a reference to the ROMol that owns this Atom

Definition at line 113 of file Atom.h.

References dp_mol.

Referenced by RDKit::queryAtomIsInRingOfSize(), RDKit::queryAtomMinRingSize(), RDKit::queryAtomRingBondCount(), RDKit::queryAtomRingMembership(), RDKit::queryIsAtomInNRings(), and RDKit::queryIsAtomInRing().

int RDKit::Atom::getPerturbationOrder ( INT_LIST probe ) const

returns the perturbation order for a list of integers

This value is associated with chirality.

Parameters:

probe

a list of bond indices. This must be the same length as our number of incoming bonds (our degree).

Returns:

the number of swaps required to convert the ordering of the probe list to match the order of our incoming bonds: e.g. if our incoming bond order is: [0,1,2,3]

	getPerturbationOrder([1,0,2,3]) = 1
	getPerturbationOrder([1,2,3,0]) = 3
	getPerturbationOrder([1,2,0,3]) = 2

See the class documentation for a more detailed description of our representation of chirality.

Notes:

requires an owning molecule

template<typename T >

void RDKit::Atom::getProp	(	const std::string	key,
		T &	res
	)			const `[inline]`

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Definition at line 329 of file Atom.h.

References dp_props, and RDKit::Dict::getVal().

template<typename T >

void RDKit::Atom::getProp	(	const char *	key,
		T &	res
	)			const `[inline]`

allows retrieval of a particular property value

Parameters:

	key	the name under which the `property` should be stored. If a `property` is already stored under this name, it will be replaced.
	res	a reference to the storage location for the value.

Notes:

if no property with name key exists, a KeyErrorException will be thrown.
the boost::lexical_cast machinery is used to attempt type conversions. If this fails, a boost::bad_lexical_cast exception will be thrown.

Definition at line 323 of file Atom.h.

References dp_props, and RDKit::Dict::getVal().

Referenced by clearComputedProps(), and setProp().

STR_VECT RDKit::Atom::getPropList ( ) const [inline]

returns a list with the names of our properties

Definition at line 272 of file Atom.h.

References dp_props, and RDKit::Dict::keys().

virtual QUERYATOM_QUERY* RDKit::Atom::getQuery ( ) const [virtual]

NOT CALLABLE.

Reimplemented in RDKit::QueryAtom.

std::string RDKit::Atom::getSymbol ( ) const

returns our symbol (determined by our atomic number)

unsigned int RDKit::Atom::getTotalDegree ( ) const

returns the total degree of the Atom (number of bonded neighbors + number of Hs)

Notes:

requires an owning molecule

Referenced by RDKit::queryAtomHeavyAtomDegree(), and RDKit::queryAtomTotalDegree().

unsigned int RDKit::Atom::getTotalNumHs ( bool includeNeighbors = false ) const

returns the total number of Hs (implicit and explicit) that this Atom is bound to

Notes:

requires an owning molecule

Referenced by RDKit::queryAtomHCount(), and RDKit::queryAtomHeavyAtomDegree().

bool RDKit::Atom::hasDativeFlag ( int what ) const [inline]

Definition at line 212 of file Atom.h.

bool RDKit::Atom::hasProp ( const std::string key ) const [inline]

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Definition at line 340 of file Atom.h.

bool RDKit::Atom::hasProp ( const char * key ) const [inline]

returns whether or not we have a property with name key

Definition at line 335 of file Atom.h.

References dp_props, and RDKit::Dict::hasVal().

Referenced by clearComputedProps(), and setProp().

virtual bool RDKit::Atom::hasQuery ( ) const [inline, virtual]

Reimplemented in RDKit::QueryAtom.

Definition at line 244 of file Atom.h.

void RDKit::Atom::initAtom ( ) [protected]

void RDKit::Atom::invertChirality ( )

inverts our chiralTag

virtual bool RDKit::Atom::Match ( const ATOM_SPTR what ) const [virtual]

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Reimplemented in RDKit::QueryAtom.

virtual bool RDKit::Atom::Match ( Atom const * what ) const [virtual]

returns whether or not we match the argument

Notes:

for Atom objects, "match" means that atomic numbers are the same.

Reimplemented in RDKit::QueryAtom.

void RDKit::Atom::setAtomicNum ( int newNum ) [inline]

sets our atomic number

Definition at line 107 of file Atom.h.

References d_atomicNum.

void RDKit::Atom::setChiralTag ( ChiralType what ) [inline]

sets our chiralTag

Definition at line 220 of file Atom.h.

References d_chiralTag.

void RDKit::Atom::setDativeFlag ( int what ) [inline]

sets our dativeFlag

Definition at line 204 of file Atom.h.

References d_dativeFlag.

void RDKit::Atom::setFormalCharge ( int what ) [inline]

set's the formal charge of this atom

Definition at line 178 of file Atom.h.

References d_formalCharge.

void RDKit::Atom::setHybridization ( HybridizationType what ) [inline]

sets our hybridization

Definition at line 227 of file Atom.h.

void RDKit::Atom::setIdx ( unsigned int index ) [inline]

sets our index within the ROMol

Notes:

this makes no sense if we do not have an owning molecule
the index should be < this->getOwningMol()->getNumAtoms()

Definition at line 123 of file Atom.h.

References d_index.

void RDKit::Atom::setIsAromatic ( bool what ) [inline]

sets our isAromatic flag, indicating whether or not we are aromatic

Definition at line 192 of file Atom.h.

void RDKit::Atom::setMass ( double what ) [inline]

sets our mass (for isotopes)

Definition at line 197 of file Atom.h.

void RDKit::Atom::setNoImplicit ( bool what ) [inline]

sets our noImplicit flag, indicating whether or not we are allowed to have implicit Hs

Definition at line 182 of file Atom.h.

void RDKit::Atom::setNumExplicitHs ( unsigned int what ) [inline]

sets our number of explict Hs

Definition at line 187 of file Atom.h.

void RDKit::Atom::setNumRadicalElectrons ( unsigned int num ) [inline]

Definition at line 172 of file Atom.h.

References d_numRadicalElectrons.

void RDKit::Atom::setOwningMol ( ROMol & other ) [inline, protected]

sets our owning molecule

Definition at line 436 of file Atom.h.

void RDKit::Atom::setOwningMol ( ROMol * other ) [protected]

sets our owning molecule

template<typename T >

void RDKit::Atom::setProp	(	const std::string	key,
		T	val,
		bool	computed = `false`
	)			const `[inline]`

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Definition at line 295 of file Atom.h.

References dp_props, getProp(), hasProp(), and RDKit::Dict::setVal().

template<typename T >

void RDKit::Atom::setProp	(	const char *	key,
		T	val,
		bool	computed = `false`
	)			const `[inline]`

sets a property value

Parameters:

	key	the name under which the `property` should be stored. If a `property` is already stored under this name, it will be replaced.
	val	the value to be stored
	computed	(optional) allows the `property` to be flagged `computed`.