rdkit/Code/GraphMol/Atom.h

//
//  Copyright (C) 2001-2024 Greg Landrum and other RDKit contributors
//
//   @@ All Rights Reserved @@
//  This file is part of the RDKit.
//  The contents are covered by the terms of the BSD license
//  which is included in the file license.txt, found at the root
//  of the RDKit source tree.
//
/*! \file Atom.h

  \brief Defines the Atom class and associated typedefs

*/
#include <RDGeneral/export.h>
#ifndef _RD_ATOM_H
#define _RD_ATOM_H

#include <limits>

// ours
#include <RDGeneral/Invariant.h>
#include <Query/QueryObjects.h>
#include <RDGeneral/types.h>
#include <RDGeneral/RDProps.h>
#include <GraphMol/details.h>

namespace RDKit {
class Atom;
}
//! allows Atom objects to be dumped to streams
RDKIT_GRAPHMOL_EXPORT std::ostream &operator<<(std::ostream &target,
                                               const RDKit::Atom &at);

namespace RDKit {
class ROMol;
class RWMol;
class AtomMonomerInfo;

//! The class for representing atoms
/*!

  <b>Notes:</b>
    - many of the methods of Atom require that the Atom be associated
      with a molecule (an ROMol).
    - each Atom maintains a Dict of \c properties:
        - Each \c property is keyed by name and can store an
          arbitrary type.
        - \c Properties can be marked as \c calculated, in which case
          they will be cleared when the \c clearComputedProps() method
          is called.
        - Because they have no impact upon chemistry, all \c property
          operations are \c 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.

  <b>Chirality:</b>

  The chirality of an Atom is determined by two things:
    - its \c chiralTag
    - the input order of its bonds (see note below for handling of
      implicit Hs)

  For tetrahedral coordination, the \c 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.

*/
class RDKIT_GRAPHMOL_EXPORT Atom : public RDProps {
  friend class MolPickler;  //!< the pickler needs access to our privates
  friend class ROMol;
  friend class RWMol;
  friend std::ostream &(::operator<<)(std::ostream &target,
                                      const ::RDKit::Atom &at);
  friend int calculateImplicitValence(const Atom &, bool, bool);

 public:
  // used to mark missing atoms, e.g. in Chirality::StereoInfo
  // and the _CIPNeighborOrder in CIP labeler
  inline static constexpr unsigned int NOATOM =
      std::numeric_limits<unsigned int>::max();

  // FIX: grn...
  typedef Queries::Query<int, Atom const *, true> QUERYATOM_QUERY;

  //! store hybridization
  typedef enum {
    UNSPECIFIED = 0,  //!< hybridization that hasn't been specified
    S,
    SP,
    SP2,
    SP3,
    SP2D,
    SP3D,
    SP3D2,
    OTHER  //!< unrecognized hybridization
  } HybridizationType;

  //! store type of chirality
  typedef enum {
    CHI_UNSPECIFIED = 0,  //!< 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
    CHI_TETRAHEDRAL,      //!< tetrahedral, use permutation flag
    CHI_ALLENE,           //!< allene, use permutation flag
    CHI_SQUAREPLANAR,     //!< square planar, use permutation flag
    CHI_TRIGONALBIPYRAMIDAL,  //!< trigonal bipyramidal, use permutation flag
    CHI_OCTAHEDRAL            //!< octahedral, use permutation flag
  } ChiralType;

  enum class ValenceType : std::uint8_t {
    IMPLICIT = 0,
    EXPLICIT
  };

  Atom();
  //! construct an Atom with a particular atomic number
  explicit Atom(unsigned int num);
  //! construct an Atom with a particular symbol (looked up in the
  /// PeriodicTable)
  explicit Atom(const std::string &what);
  Atom(const Atom &other);
  Atom &operator=(const Atom &other);
  // NOTE: the move methods are somewhat fraught for atoms associated with
  // molecules since the molecule will still be pointing to the original object
  Atom(Atom &&other) = default;
  Atom &operator=(Atom &&other) = default;

  virtual ~Atom();

  //! makes a copy of this Atom and returns a pointer to it.
  /*!
    <b>Note:</b> the caller is responsible for <tt>delete</tt>ing the result
  */
  virtual Atom *copy() const;

  //! returns our atomic number
  int getAtomicNum() const { return d_atomicNum; }
  //! sets our atomic number
  void setAtomicNum(int newNum) { d_atomicNum = newNum; }

  //! returns our symbol (determined by our atomic number)
  std::string getSymbol() const;

  //! returns whether or not this instance belongs to a molecule
  bool hasOwningMol() const { return dp_mol != nullptr; }

  //! returns a reference to the ROMol that owns this instance
  ROMol &getOwningMol() const {
    PRECONDITION(dp_mol, "no owner");
    return *dp_mol;
  }

  //! returns our index within the ROMol
  unsigned int getIdx() const { return d_index; }
  //! sets our index within the ROMol
  /*!
    <b>Notes:</b>
      - this makes no sense if we do not have an owning molecule
      - the index should be <tt>< this->getOwningMol()->getNumAtoms()</tt>
  */
  void setIdx(unsigned int index) { d_index = index; }
  //! overload
  template <class U>
  void setIdx(const U index) {
    setIdx(rdcast<unsigned int>(index));
  }
  //! returns the explicit degree of the Atom (number of bonded
  //!   neighbors in the graph)
  unsigned int getDegree() const;

  //! returns the total degree of the Atom (number of bonded
  //!   neighbors + number of Hs)
  unsigned int getTotalDegree() const;

  //! \brief returns the total number of Hs (implicit and explicit) that
  //! this Atom is bound to
  unsigned int getTotalNumHs(bool includeNeighbors = false) const;

  //! \brief returns the total valence (implicit and explicit)
  //! for an atom
  unsigned int getTotalValence() const;

  //! returns the number of implicit Hs this Atom is bound to
  unsigned int getNumImplicitHs() const;

  //! returns the valence (explicit or implicit) of this atom
  unsigned int getValence(ValenceType which) const;

  //! returns the explicit valence (including Hs) of this atom
  [[deprecated("please use getValence(true)")]] int getExplicitValence() const;

  //! returns the implicit valence for this Atom
  [[deprecated("please use getValence(false)")]] int getImplicitValence() const;

  //! returns whether the atom has a valency violation or not
  bool hasValenceViolation() const;

  //! returns the number of radical electrons for this Atom
  unsigned int getNumRadicalElectrons() const { return d_numRadicalElectrons; }
  void setNumRadicalElectrons(unsigned int num) { d_numRadicalElectrons = num; }

  //! returns the formal charge of this atom
  int getFormalCharge() const { return d_formalCharge; }
  //! set's the formal charge of this atom
  void setFormalCharge(int what) { d_formalCharge = what; }

  //! \brief sets our \c noImplicit flag, indicating whether or not
  //!  we are allowed to have implicit Hs
  void setNoImplicit(bool what) { df_noImplicit = what; }
  //! returns the \c noImplicit flag
  bool getNoImplicit() const { return df_noImplicit; }

  //! sets our number of explicit Hs
  void setNumExplicitHs(unsigned int what) { d_numExplicitHs = what; }
  //! returns our number of explicit Hs
  unsigned int getNumExplicitHs() const { return d_numExplicitHs; }

  //! sets our \c isAromatic flag, indicating whether or not we are aromatic
  void setIsAromatic(bool what) { df_isAromatic = what; }
  //! returns our \c isAromatic flag
  bool getIsAromatic() const { return df_isAromatic; }

  //! returns our mass
  double getMass() const;

  //! sets our isotope number
  void setIsotope(unsigned int what);
  //! returns our isotope number
  unsigned int getIsotope() const { return d_isotope; }

  //! sets our \c chiralTag
  void setChiralTag(ChiralType what) { d_chiralTag = what; }
  //! inverts our \c chiralTag, returns whether or not a change was made
  bool invertChirality();
  //! returns our \c chiralTag
  ChiralType getChiralTag() const {
    return static_cast<ChiralType>(d_chiralTag);
  }

  //! sets our hybridization
  void setHybridization(HybridizationType what) { d_hybrid = what; }
  //! returns our hybridization
  HybridizationType getHybridization() const {
    return static_cast<HybridizationType>(d_hybrid);
  }

  // ------------------------------------
  // Some words of explanation before getting down into
  // the query stuff.
  // These query functions are really only here so that they
  //  can have real functionality in subclasses (like QueryAtoms).
  // Since pretty much it's gonna be a mistake to call any of these
  //  (ever), we're saddling them all with a precondition which
  //  is guaranteed to fail.  I'd like to have them be pure virtual,
  //  but that doesn't work since we need to be able to instantiate
  //  Atoms.
  // ------------------------------------

  // This method can be used to distinguish query atoms from standard atoms:
  virtual bool hasQuery() const { return false; }

  virtual std::string getQueryType() const { return ""; }

  //! NOT CALLABLE
  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);

  //! returns whether or not we match the argument
  /*!
      <b>Notes:</b>
        The general rule is that if a property on this atom has a non-default
     value,
        the property on the other atom must have the same value.
        The exception to this is H counts, which are ignored. These turns out to
     be
          impossible to handle generally, so rather than having odd and
     hard-to-explain
          exceptions, we ignore them entirely.

        Here are the rules for atom-atom matching:
        | This    | Other   | Match | Reason
        | CCO     | CCO     | Yes   |
        | CCO     | CC[O-]  | Yes   |
        | CC[O-]  | CCO     | No    | Charge
        | CC[O-]  | CC[O-]  | Yes   |
        | CC[OH]  | CC[O-]  | Yes   |
        | CC[OH]  | CCOC    | Yes   |
        | CCO     | CCOC    | Yes   |
        | CCC     | CCC     | Yes   |
        | CCC     | CC[14C] | Yes   |
        | CC[14C] | CCC     | No    | Isotope
        | CC[14C] | CC[14C] | Yes   |
        | C       | OCO     | Yes   |
        | [CH]    | OCO     | Yes   |
        | [CH2]   | OCO     | Yes   |
        | [CH3]   | OCO     | No    | Radical
        | C       | O[CH2]O | Yes   |
        | [CH2]   | O[CH2]O | Yes   |
  */
  virtual bool Match(Atom const *what) const;

  //! returns the perturbation order for a list of integers
  /*!

    This value is associated with chirality.

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

    \return 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: <tt>[0,1,2,3]</tt>
      \verbatim
      getPerturbationOrder([1,0,2,3]) = 1
      getPerturbationOrder([1,2,3,0]) = 3
      getPerturbationOrder([1,2,0,3]) = 2
      \endverbatim

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

    <b>Notes:</b>
      - requires an owning molecule

  */
  int getPerturbationOrder(const INT_LIST &probe) const;

  //! calculates any of our lazy \c properties
  /*!
    <b>Notes:</b>
      - requires an owning molecule
      - the current lazy \c properties are implicit and explicit valence
  */
  void updatePropertyCache(bool strict = true);

  bool needsUpdatePropertyCache() const;
  void clearPropertyCache();

  //! calculates and returns our explicit valence
  /*!
    <b>Notes:</b>
      - requires an owning molecule
  */
  int calcExplicitValence(bool strict = true);

  //! calculates and returns our implicit valence
  /*!
    <b>Notes:</b>
      - requires an owning molecule
  */
  int calcImplicitValence(bool strict = true);

  AtomMonomerInfo *getMonomerInfo() { return dp_monomerInfo; }
  const AtomMonomerInfo *getMonomerInfo() const { return dp_monomerInfo; }
  //! takes ownership of the pointer
  void setMonomerInfo(AtomMonomerInfo *info);

  //! Set the atom map Number of the atom
  void setAtomMapNum(int mapno, bool strict = true) {
    PRECONDITION(
        !strict || (mapno >= 0 && mapno < 1000),
        "atom map number out of range [0..1000], use strict=false to override");
    if (mapno) {
      setProp(common_properties::molAtomMapNumber, mapno);
    } else if (hasProp(common_properties::molAtomMapNumber)) {
      clearProp(common_properties::molAtomMapNumber);
    }
  }
  //! Gets the atom map Number of the atom, if no atom map exists, 0 is
  //! returned.
  int getAtomMapNum() const {
    int mapno = 0;
    getPropIfPresent(common_properties::molAtomMapNumber, mapno);
    return mapno;
  }

  //! Flags that can be used by to store information on atoms.
  //!   These are not serialized and should be treated as temporary values.
  //!   No guarantees are made about preserving these flags across library
  //!   calls.
  void setFlags(std::uint64_t flags) { d_flags = flags; }
  std::uint64_t getFlags() const { return d_flags; }
  std::uint64_t &getFlags() { return d_flags; }

 protected:
  //! sets our owning molecule
  void setOwningMol(ROMol *other);
  //! sets our owning molecule
  void setOwningMol(ROMol &other) { setOwningMol(&other); }

  bool df_isAromatic;
  bool df_noImplicit;
  std::uint8_t d_numExplicitHs;
  std::int8_t d_formalCharge;
  std::uint8_t d_atomicNum;
  // NOTE that these cannot be signed, they are calculated using
  // a lazy scheme and are initialized to -1 to indicate that the
  // calculation has not yet been done.
  std::int8_t d_implicitValence, d_explicitValence;
  std::uint8_t d_numRadicalElectrons;
  std::uint8_t d_chiralTag;
  std::uint8_t d_hybrid;

  std::uint16_t d_isotope;
  atomindex_t d_index;
  std::uint64_t d_flags = 0ul;

  ROMol *dp_mol;
  AtomMonomerInfo *dp_monomerInfo;
  void initAtom();
  void initFromOther(const Atom &other);
};

//! Set the atom's MDL integer RLabel
///  Setting to 0 clears the rlabel.  Rlabel must be in the range [0..99]
RDKIT_GRAPHMOL_EXPORT void setAtomRLabel(Atom *atm, int rlabel);
RDKIT_GRAPHMOL_EXPORT int getAtomRLabel(const Atom *atm);

//! Set the atom's MDL atom alias
///  Setting to an empty string clears the alias
RDKIT_GRAPHMOL_EXPORT void setAtomAlias(Atom *atom, const std::string &alias);
RDKIT_GRAPHMOL_EXPORT std::string getAtomAlias(const Atom *atom);

//! Set the atom's MDL atom value
///  Setting to an empty string clears the value
///  This is where recursive smarts get stored in MolBlock Queries
RDKIT_GRAPHMOL_EXPORT void setAtomValue(Atom *atom, const std::string &value);
RDKIT_GRAPHMOL_EXPORT std::string getAtomValue(const Atom *atom);

//! Sets the supplemental label that will follow the atom when writing
///  smiles strings.
RDKIT_GRAPHMOL_EXPORT void setSupplementalSmilesLabel(Atom *atom,
                                                      const std::string &label);
RDKIT_GRAPHMOL_EXPORT std::string getSupplementalSmilesLabel(const Atom *atom);

//! returns true if the atom is to the left of C
RDKIT_GRAPHMOL_EXPORT bool isEarlyAtom(int atomicNum);
//! returns true if the atom is aromatic or has an aromatic bond
RDKIT_GRAPHMOL_EXPORT bool isAromaticAtom(const Atom &atom);
//! returns the number of pi electrons on the atom
RDKIT_GRAPHMOL_EXPORT unsigned int numPiElectrons(const Atom &atom);
};  // namespace RDKit

//! allows Atom objects to be dumped to streams
RDKIT_GRAPHMOL_EXPORT std::ostream &operator<<(std::ostream &target,
                                               const RDKit::Atom &at);
#endif