mol.h

Go to the documentation of this file.

/**********************************************************************
mol.h - Handle molecules. Declarations of OBMol, OBAtom, OBBond, OBResidue.
        (the main header for Open Babel)

Copyright (C) 1998-2001 by OpenEye Scientific Software, Inc.
Some portions Copyright (C) 2001-2006 by Geoffrey R. Hutchison
Some portions Copyright (C) 2003 by Michael Banck

This file is part of the Open Babel project.
For more information, see <http://openbabel.org/>

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation version 2 of the License.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.
***********************************************************************/

#ifndef OB_MOL_H
#define OB_MOL_H

#include <openbabel/babelconfig.h>

#ifndef EXTERN
#  define EXTERN extern
#endif
#ifndef THREAD_LOCAL
#ifdef SWIG
# define THREAD_LOCAL
# elif (__cplusplus >= 201103L) 
//this is required for correct multi-threading
#  define THREAD_LOCAL thread_local
# else
#  define THREAD_LOCAL
# endif
#endif

#include <math.h>
#include <float.h>

#include <vector>
#include <string>
#include <map>

#include <openbabel/base.h>


namespace OpenBabel
{
  class OBAtom;
  class OBBond;
  class OBResidue;
  class OBRing;
  class OBInternalCoord;
  class OBConversion; //used only as a pointer

  class vector3;
  class OBBitVec;
  class OBMolAtomDFSIter;
  class OBChainsParser;

  typedef std::vector<OBAtom*>::iterator OBAtomIterator;
  typedef std::vector<OBBond*>::iterator OBBondIterator;
  typedef std::vector<OBResidue*>::iterator OBResidueIterator;

  // Class OBMol
  //MOL Property Macros (flags) -- 32+ bits
#define OB_SSSR_MOL              (1<<1)
#define OB_RINGFLAGS_MOL         (1<<2)
#define OB_AROMATIC_MOL          (1<<3)
#define OB_ATOMTYPES_MOL         (1<<4)
#define OB_CHIRALITY_MOL         (1<<5)
#define OB_PCHARGE_MOL           (1<<6)
#define OB_HYBRID_MOL            (1<<8)
#define OB_CLOSURE_MOL           (1<<11)
#define OB_H_ADDED_MOL           (1<<12)
#define OB_PH_CORRECTED_MOL      (1<<13)
#define OB_CHAINS_MOL            (1<<15)
#define OB_TCHARGE_MOL                 (1<<16)
#define OB_TSPIN_MOL             (1<<17)
#define OB_RINGTYPES_MOL         (1<<18)
#define OB_PATTERN_STRUCTURE     (1<<19)
#define OB_LSSR_MOL              (1<<20)
#define OB_ATOMSPIN_MOL          (1<<21)
#define OB_REACTION_MOL          (1<<22)
  // flags 22-32 unspecified

#define SET_OR_UNSET_FLAG(X) \
  if (value) SetFlag(X); \
  else     UnsetFlag(X);

#define OB_CURRENT_CONFORMER     -1

enum HydrogenType { AllHydrogen, PolarHydrogen, NonPolarHydrogen };

  // class introduction in mol.cpp
 class OBAPI OBMol: public OBBase
  {
  protected:
    int                           _flags;       
    bool                          _autoPartialCharge;
    bool                          _autoFormalCharge;
    std::string                   _title;       
    std::vector<OBAtom*>          _vatom;       
    std::vector<OBAtom*>          _atomIds;     
    std::vector<OBBond*>          _vbond;       
    std::vector<OBBond*>          _bondIds;     
    unsigned short int            _dimension;   
    int                           _totalCharge; 
    unsigned int                  _totalSpin;   
    double                        *_c;          
    std::vector<double*>          _vconf;       
    double                        _energy;      
    unsigned int                  _natoms;      
    unsigned int                  _nbonds;      
    std::vector<OBResidue*>       _residue;     
    std::vector<OBInternalCoord*> _internals;   
    unsigned short int            _mod;         

  public:


    OBMol();
    OBMol(const OBMol &);
    virtual ~OBMol();
    OBMol &operator=(const OBMol &mol);
    OBMol &operator+=(const OBMol &mol);

    void ReserveAtoms(int natoms)
    {
      if (natoms > 0 && _mod) {
        _vatom.reserve(natoms);
        _atomIds.reserve(natoms);
      }
    }

    virtual void DestroyAtom(OBAtom*);
    virtual void DestroyBond(OBBond*);
    virtual void DestroyResidue(OBResidue*);

    bool AddAtom(OBAtom& atom, bool forceNewId = false);
    bool InsertAtom(OBAtom &);
    bool AddBond(int beginIdx, int endIdx, int order,
                 int flags=0,int insertpos=-1);
    bool AddBond(OBBond&);
    bool AddResidue(OBResidue&);

    OBAtom    *NewAtom();
    OBAtom    *NewAtom(unsigned long id);
    OBBond    *NewBond();
    OBBond    *NewBond(unsigned long id);
    OBResidue *NewResidue();
    bool DeleteAtom(OBAtom*, bool destroyAtom = true);
    bool DeleteBond(OBBond*, bool destroyBond = true);
    bool DeleteResidue(OBResidue*, bool destroyResidue = true);


    virtual void BeginModify(void);
    virtual void EndModify(bool nukePerceivedData=true);
    int GetMod()           {      return(_mod);    }
    void IncrementMod()    {      _mod++;          }
    void DecrementMod()    {      _mod--;          }


    int          GetFlags()               { return(_flags); }
    const char  *GetTitle(bool replaceNewlines = true) const;
    unsigned int NumAtoms() const         {  return(_natoms); }
    unsigned int NumBonds() const         {  return(_nbonds); }
    unsigned int NumHvyAtoms();
    unsigned int NumResidues() const      { return(static_cast<unsigned int> (_residue.size())); }
    unsigned int NumRotors(bool sampleRingBonds=false);

    OBAtom      *GetAtom(int idx) const;
    OBAtom      *GetAtomById(unsigned long id) const;
    OBAtom      *GetFirstAtom() const;
    OBBond      *GetBond(int idx) const;
    OBBond      *GetBondById(unsigned long id) const;
    OBBond      *GetBond(int a, int b) const;
    // The safer version of the above method
    OBBond      *GetBond(OBAtom* bgn, OBAtom* end) const;
    OBResidue   *GetResidue(int idx) const;
    std::vector<OBInternalCoord*> GetInternalCoord();
    double       GetTorsion(int,int,int,int);
    double       GetTorsion(OBAtom* a,OBAtom* b,OBAtom* c,OBAtom* d);
    double GetAngle(OBAtom* a, OBAtom* b, OBAtom* c);
    int AreInSameRing(OBAtom *a, OBAtom *b);
    std::string  GetFormula();
    std::string  GetSpacedFormula(int ones=0, const char* sp=" ", bool implicitH = true);
    double       GetEnergy() const { return _energy; }
    double       GetMolWt(bool implicitH = true);
    double       GetExactMass(bool implicitH = true);
    int          GetTotalCharge();
    unsigned int GetTotalSpinMultiplicity();
    unsigned short int GetDimension() const { return _dimension; }
    double      *GetCoordinates() { return(_c); }
    std::vector<OBRing*> &GetSSSR();
    std::vector<OBRing*> &GetLSSR();
    bool AutomaticFormalCharge()   { return(_autoFormalCharge);  }
    bool AutomaticPartialCharge()  { return(_autoPartialCharge); }



    void   SetTitle(const char *title);
    void   SetTitle(std::string &title);
    void   SetFormula(std::string molFormula);
    void   SetEnergy(double energy) { _energy = energy; }
    void   SetDimension(unsigned short int d) { _dimension = d; }
    void   SetTotalCharge(int charge);
    void   SetTotalSpinMultiplicity(unsigned int spinMultiplicity);
    void SetInternalCoord(std::vector<OBInternalCoord*> int_coord);
    void SetAutomaticFormalCharge(bool val)
    { _autoFormalCharge=val;  }
    void SetAutomaticPartialCharge(bool val)
    { _autoPartialCharge=val; }

    void   SetAromaticPerceived(bool value = true)    { SET_OR_UNSET_FLAG(OB_AROMATIC_MOL);    }
    void   SetSSSRPerceived(bool value = true)        { SET_OR_UNSET_FLAG(OB_SSSR_MOL);        }
    void   SetLSSRPerceived(bool value = true)        { SET_OR_UNSET_FLAG(OB_LSSR_MOL);        }
    void   SetRingAtomsAndBondsPerceived(bool value = true) { SET_OR_UNSET_FLAG(OB_RINGFLAGS_MOL); }
    void   SetAtomTypesPerceived(bool value = true)   { SET_OR_UNSET_FLAG(OB_ATOMTYPES_MOL);   }
    void   SetRingTypesPerceived(bool value = true)   { SET_OR_UNSET_FLAG(OB_RINGTYPES_MOL);   }
    void   SetChainsPerceived(bool value = true)      { SET_OR_UNSET_FLAG(OB_CHAINS_MOL);      }
    void   SetChiralityPerceived(bool value = true)   { SET_OR_UNSET_FLAG(OB_CHIRALITY_MOL);   }
    void   SetPartialChargesPerceived(bool value = true) { SET_OR_UNSET_FLAG(OB_PCHARGE_MOL);  }
    void   SetHybridizationPerceived(bool value = true)  { SET_OR_UNSET_FLAG(OB_HYBRID_MOL);   }
    void   SetClosureBondsPerceived(bool value = true)   { SET_OR_UNSET_FLAG(OB_CLOSURE_MOL);  }
    void   SetHydrogensAdded(bool value = true) { SET_OR_UNSET_FLAG(OB_H_ADDED_MOL); }
    void   SetCorrectedForPH(bool value = true) { SET_OR_UNSET_FLAG(OB_PH_CORRECTED_MOL); }
    void   SetSpinMultiplicityAssigned(bool value = true) { SET_OR_UNSET_FLAG(OB_ATOMSPIN_MOL); }
    void   SetIsPatternStructure(bool value = true) { SET_OR_UNSET_FLAG(OB_PATTERN_STRUCTURE); }
    void   SetIsReaction(bool value = true)               { SET_OR_UNSET_FLAG(OB_REACTION_MOL) };
    bool   HasFlag(int flag)   { return (_flags & flag) ? true : false; }
    void   SetFlag(int flag)   { _flags |= flag; }
    void   UnsetFlag(int flag) { _flags &= (~(flag)); }
    void   SetFlags(int flags) { _flags = flags; }


    // Description in transform.cpp (command-line transformations to this molecule)
    virtual OBBase*    DoTransformations(const std::map<std::string,std::string>* pOptions,OBConversion* pConv);
    // Ditto (documentation on transformation options)
    static const char* ClassDescription();
    bool Clear();
    void RenumberAtoms(std::vector<OBAtom*>&);
    void RenumberAtoms(std::vector<int>);
    void SetCoordinates(double *c);
    void ToInertialFrame(int conf, double *rmat);
    void ToInertialFrame();
    void Translate(const vector3 &v);
    void Translate(const vector3 &v, int conf);
    void Rotate(const double u[3][3]);
    void Rotate(const double m[9]);
    void Rotate(const double m[9],int nconf);
    void Center();
    bool DeleteHydrogens();
    bool DeleteHydrogens(OBAtom*);
    bool DeletePolarHydrogens();
    bool DeleteNonPolarHydrogens();
    bool DeleteHydrogen(OBAtom*);
    bool AddHydrogens(bool polaronly=false,bool correctForPH=false, double pH=7.4);
    bool AddHydrogens(OBAtom*);
    bool AddPolarHydrogens();
    bool AddNonPolarHydrogens();
    bool AddNewHydrogens(HydrogenType whichHydrogen, bool correctForPH=false, double pH=7.4);

    bool StripSalts(unsigned int threshold=0);
    std::vector<OBMol> Separate(int StartIndex=1);
    bool GetNextFragment( OpenBabel::OBMolAtomDFSIter& iter, OBMol& newMol );
    // docs in mol.cpp
    bool CopySubstructure(OBMol& newmol, OBBitVec *includeatoms, OBBitVec *excludebonds = (OBBitVec*)0,
      unsigned int correctvalence=1,
      std::vector<unsigned int> *atomorder=(std::vector<unsigned int>*)0,
      std::vector<unsigned int> *bondorder=(std::vector<unsigned int>*)0);
    bool ConvertDativeBonds();
    bool MakeDativeBonds();
    bool ConvertZeroBonds();

    bool CorrectForPH(double pH=7.4);
    // docs in mol.cpp
    bool AssignSpinMultiplicity(bool NoImplicitH=false);

    bool AssignTotalChargeToAtoms(int charge);

    vector3 Center(int nconf);
    void SetTorsion(OBAtom*,OBAtom*,OBAtom*,OBAtom*,double ang);


    void FindSSSR();
    void FindLSSR();
    void FindRingAtomsAndBonds();
    // documented in mol.cpp -- locates all atom indexes which can reach 'end'
    void FindChildren(std::vector<int> & children,int bgnIdx,int endIdx);
    // documented in mol.cpp -- locates all atoms which can reach 'end'
    void FindChildren(std::vector<OBAtom*>& children,OBAtom* bgn,OBAtom* end);
    void FindLargestFragment(OBBitVec &frag);
    void ContigFragList(std::vector<std::vector<int> >&);
    void Align(OBAtom*,OBAtom*,vector3&,vector3&);
    void ConnectTheDots();
    void PerceiveBondOrders();
    void FindAngles();
    void FindTorsions();
    // documented in mol.cpp: graph-theoretical distance for each atom
    bool         GetGTDVector(std::vector<int> &);
    // documented in mol.cpp: graph-invariant index for each atom
    void         GetGIVector(std::vector<unsigned int> &);
    // documented in mol.cpp: calculate symmetry-unique identifiers
    void         GetGIDVector(std::vector<unsigned int> &);


    bool Has2D(bool Not3D=false);
    bool Has3D();
    bool HasNonZeroCoords();
    bool HasAromaticPerceived()     { return(HasFlag(OB_AROMATIC_MOL)); }
    bool HasSSSRPerceived()         { return(HasFlag(OB_SSSR_MOL));     }
    bool HasLSSRPerceived()         { return(HasFlag(OB_LSSR_MOL));     }
    bool HasRingAtomsAndBondsPerceived(){return(HasFlag(OB_RINGFLAGS_MOL));}
    bool HasAtomTypesPerceived()    { return(HasFlag(OB_ATOMTYPES_MOL));}
    bool HasRingTypesPerceived()    { return(HasFlag(OB_RINGTYPES_MOL));}
    bool HasChiralityPerceived()    { return(HasFlag(OB_CHIRALITY_MOL));}
    bool HasPartialChargesPerceived() { return(HasFlag(OB_PCHARGE_MOL));}
    bool HasHybridizationPerceived() { return(HasFlag(OB_HYBRID_MOL));  }
    bool HasClosureBondsPerceived() { return(HasFlag(OB_CLOSURE_MOL));  }
    bool HasChainsPerceived() { return(HasFlag(OB_CHAINS_MOL));         }
    bool HasHydrogensAdded() { return(HasFlag(OB_H_ADDED_MOL));         }
    bool IsCorrectedForPH() { return(HasFlag(OB_PH_CORRECTED_MOL));     }
    bool HasSpinMultiplicityAssigned() { return(HasFlag(OB_ATOMSPIN_MOL)); }
    bool IsReaction()                  { return HasFlag(OB_REACTION_MOL); }
    bool Empty()                       { return(_natoms == 0);          }


    int     NumConformers()    { return((_vconf.empty())?0:static_cast<int> (_vconf.size())); }
    void    SetConformers(std::vector<double*> &v);
    void    AddConformer(double *f)    {  _vconf.push_back(f);    }
    void    SetConformer(unsigned int i);
    void    CopyConformer(double* c,int nconf);
    void    DeleteConformer(int nconf);
    double  *GetConformer(int i)       {  return(_vconf[i]);      }
    void    SetEnergies(std::vector<double> &energies);
    std::vector<double> GetEnergies();
    double  GetEnergy(int ci);
    double  *BeginConformer(std::vector<double*>::iterator&i)
    { i = _vconf.begin();
      return((i == _vconf.end()) ? NULL:*i); }
    double  *NextConformer(std::vector<double*>::iterator&i)
    { ++i;
      return((i == _vconf.end()) ? NULL:*i); }
    std::vector<double*> &GetConformers() {   return(_vconf);     }


    OBAtomIterator BeginAtoms()   { return _vatom.begin(); }
    OBAtomIterator EndAtoms()    { return _vatom.begin() + NumAtoms() ; }
    OBBondIterator BeginBonds()   { return _vbond.begin(); }
    OBBondIterator EndBonds()     { return _vbond.begin() + NumBonds() ; }
    OBResidueIterator BeginResidues() { return _residue.begin(); }
    OBResidueIterator EndResidues()   { return _residue.end();   }

    OBAtom *BeginAtom(OBAtomIterator &i);
    OBAtom *NextAtom(OBAtomIterator &i);
    OBBond *BeginBond(OBBondIterator &i);
    OBBond *NextBond(OBBondIterator &i);
    OBResidue *BeginResidue(OBResidueIterator &i)
    {
      i = _residue.begin();
      return((i == _residue.end()) ? NULL:*i);
    }
    OBResidue *NextResidue(OBResidueIterator &i)
    {
      ++i;
      return((i == _residue.end()) ? NULL:*i);
    }
    OBInternalCoord *BeginInternalCoord(std::vector<OBInternalCoord*>::iterator &i)
    {
      i = _internals.begin();
      return((i == _internals.end()) ? NULL:*i);
    }
    OBInternalCoord *NextInternalCoord(std::vector<OBInternalCoord*>::iterator &i)
    {
      ++i;
      return((i == _internals.end()) ? NULL:*i);
    }

  };

  // Utility function prototypes
  //tokenize and Trim declarations moved to base.h
  // Deprecated -- use OBMessageHandler class instead (docs in obutil.cpp)
  OBAPI void ThrowError(char *str);
  // Deprecated -- use OBMessageHandler class instead (docs in obutil.cpp)
  OBAPI void ThrowError(std::string &str);
  OBAPI void CartesianToInternal(std::vector<OBInternalCoord*>&,OBMol&);
  OBAPI void InternalToCartesian(std::vector<OBInternalCoord*>&,OBMol&);
  // Replace the last extension in str with a new one (docs in obutil.cpp)
  OBAPI std::string NewExtension(std::string&,char*);

  namespace detail {
    template<typename T, int size = sizeof(T)>
    struct max_value
    {
      static const T result = (static_cast<T>(0xFF) << (size-1)*8) + max_value<T, size-1>::result;
    };

    template<typename T>
    struct max_value<T, 0>
    {
      static const T result = 0;
    };
  }

  // No unique id
  static const unsigned long NoId = detail::max_value<unsigned long>::result;

  //Utility Macros

#ifndef BUFF_SIZE
#define BUFF_SIZE 32768
#endif

#ifndef EQ
#define EQ(a,b) (!strcmp((a), (b)))
#endif

#ifndef EQn
#define EQn(a,b,n) (!strncmp((a), (b), (n)))
#endif

#ifndef SQUARE
#define SQUARE(x) ((x)*(x))
#endif

#ifndef IsUnsatType
#define IsUnsatType(x)  (EQ(x,"Car") || EQ(x,"C2") || EQ(x,"Sox") || EQ(x,"Sac") || EQ(x,"Pac") || EQ(x,"So2"))
#endif

#ifndef __KCC
  extern "C"
  {
    OBAPI void  get_rmat(double*,double*,double*,int);
    OBAPI void  ob_make_rmat(double mat[3][3],double rmat[9]);
    OBAPI void  qtrfit (double *r,double *f,int size,double u[3][3]);
    OBAPI double superimpose(double*,double*,int);
  }
#else
  OBAPI void get_rmat(double*,double*,double*,int);
  OBAPI void ob_make_rmat(double mat[3][3],double rmat[9]);
  OBAPI void qtrfit (double *r,double *f,int size,double u[3][3]);
  OBAPI double superimpose(double*,double*,int);
#endif // __KCC

//  extern OBMol* (*CreateMolecule) (void);

} // end namespace OpenBabel

#endif // OB_MOL_H