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

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

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

// Currently includes many headers for 2.x backwards compatibility
// \deprecated -- this will be cleaned up in 3.0 efforts
//      to improve compile time significantly.
// Only include necessary headers and class declaration stubs.
#include <openbabel/atom.h>
#include <openbabel/bond.h>
#include <openbabel/base.h>
#include <openbabel/data.h>
#include <openbabel/chains.h>
#include <openbabel/math/vector3.h>
#include <openbabel/bitvec.h>
#include <openbabel/residue.h>
#include <openbabel/ring.h>
#include <openbabel/generic.h>
#include <openbabel/typer.h>
#include <openbabel/oberror.h>
#include <openbabel/obiter.h>
#include <openbabel/internalcoord.h>

namespace OpenBabel
{

  class OBAtom;
  class OBBond;
  class OBInternalCoord;
  class OBConversion; //used only as a pointer

  // 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_IMPVAL_MOL            (1<<9)

#define OB_KEKULE_MOL            (1<<10)

#define OB_CLOSURE_MOL           (1<<11)

#define OB_H_ADDED_MOL           (1<<12)

#define OB_PH_CORRECTED_MOL      (1<<13)

#define OB_AROM_CORRECTED_MOL    (1<<14)

#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)
  // flags 21-32 unspecified
#define OB_CURRENT_CONFORMER     -1

  // 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;         

    bool  HasFlag(int flag)    { return((_flags & flag) ? true : false); }
    void  SetFlag(int flag)    { _flags |= flag; }


    void start_kekulize(std::vector <OBAtom*> &cycle, std::vector<int> &electron);
    bool expand_kekulize(int bond_idx, std::vector<int> &atomState, std::vector<int> &bondState);
    bool has_no_leftover_electrons(std::vector<int> &atomState);
    int getorden(OBAtom *atom);
    bool expandcycle(OBAtom *atom, OBBitVec &avisit, const OBBitVec &potAromBonds);

  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 OBAtom *CreateAtom(void);
    virtual OBBond *CreateBond(void);
    virtual OBResidue *CreateResidue(void);
    virtual void DestroyAtom(OBAtom*);
    virtual void DestroyBond(OBBond*);
    virtual void DestroyResidue(OBResidue*);

    bool AddAtom(OBAtom&);
    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();

    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);
    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()    { SetFlag(OB_AROMATIC_MOL);    }
    void   SetSSSRPerceived()        { SetFlag(OB_SSSR_MOL);        }
    void   SetLSSRPerceived()        { SetFlag(OB_LSSR_MOL);        }
    void   SetRingAtomsAndBondsPerceived(){SetFlag(OB_RINGFLAGS_MOL);}
    void   SetAtomTypesPerceived()   { SetFlag(OB_ATOMTYPES_MOL);   }
    void   SetRingTypesPerceived()   { SetFlag(OB_RINGTYPES_MOL);   }
    void   SetChainsPerceived()      { SetFlag(OB_CHAINS_MOL);      }
    void   SetChiralityPerceived()   { SetFlag(OB_CHIRALITY_MOL);   }
    void   SetPartialChargesPerceived(){ SetFlag(OB_PCHARGE_MOL);   }
    void   SetHybridizationPerceived() { SetFlag(OB_HYBRID_MOL);    }
    void   SetImplicitValencePerceived(){ SetFlag(OB_IMPVAL_MOL);   }
    void   SetKekulePerceived()      { SetFlag(OB_KEKULE_MOL);      }
    void   SetClosureBondsPerceived(){ SetFlag(OB_CLOSURE_MOL);     }
    void   SetHydrogensAdded()       { SetFlag(OB_H_ADDED_MOL);     }
    void   SetCorrectedForPH()       { SetFlag(OB_PH_CORRECTED_MOL);}
    void   SetAromaticCorrected()    { SetFlag(OB_AROM_CORRECTED_MOL);}
    void   SetSpinMultiplicityAssigned(){ SetFlag(OB_TSPIN_MOL);    }
    void   SetFlags(int flags)       { _flags = flags;              }

    void   UnsetAromaticPerceived()  { _flags &= (~(OB_AROMATIC_MOL));   }
    void   UnsetSSSRPerceived()  { _flags &= (~(OB_SSSR_MOL));   }
    void   UnsetRingTypesPerceived()  { _flags &= (~(OB_RINGTYPES_MOL));   }
    void   UnsetPartialChargesPerceived(){ _flags &= (~(OB_PCHARGE_MOL));}
    void   UnsetImplicitValencePerceived(){_flags &= (~(OB_IMPVAL_MOL)); }
    void   UnsetHydrogensAdded()       { UnsetFlag(OB_H_ADDED_MOL);     }
    void   UnsetFlag(int flag)       { _flags &= (~(flag));              }


    // 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 Kekulize();
    bool PerceiveKekuleBonds();

    void NewPerceiveKekuleBonds();

    bool DeleteHydrogens();
    bool DeleteHydrogens(OBAtom*);
    bool DeleteNonPolarHydrogens();
    bool DeleteHydrogen(OBAtom*);
    bool AddHydrogens(bool polaronly=false,bool correctForPH=false, double pH=7.4);
    bool AddHydrogens(OBAtom*);
    bool AddPolarHydrogens();

    bool StripSalts(int threshold=0);
    std::vector<OBMol> Separate(int StartIndex=1);
    bool GetNextFragment( OpenBabel::OBMolAtomDFSIter& iter, OBMol& newMol );
    bool ConvertDativeBonds();

    bool CorrectForPH(double pH=7.4);
    // docs in mol.cpp
    bool AssignSpinMultiplicity(bool NoImplicitH=false);
    void   SetIsPatternStructure()       { SetFlag(OB_PATTERN_STRUCTURE);}

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



    void FindSSSR();
    void FindLSSR();
    void FindRingAtomsAndBonds();
    void FindChiralCenters() { IsChiral(); }
    // 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 HasImplicitValencePerceived() { return(HasFlag(OB_IMPVAL_MOL));}
    bool HasKekulePerceived() { return(HasFlag(OB_KEKULE_MOL));         }
    bool HasClosureBondsPerceived() { return(HasFlag(OB_CLOSURE_MOL));  }
    bool HasChainsPerceived() { return(HasFlag(OB_CHAINS_MOL));         }
    bool HasHydrogensAdded() { return(HasFlag(OB_H_ADDED_MOL));         }
    bool HasAromaticCorrected() { return(HasFlag(OB_AROM_CORRECTED_MOL));}
    bool IsCorrectedForPH() { return(HasFlag(OB_PH_CORRECTED_MOL));     }
    bool HasSpinMultiplicityAssigned() { return(HasFlag(OB_TSPIN_MOL)); }
    bool IsChiral();
    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(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*);

  //global definitions
  EXTERN  OBElementTable   etab;
  EXTERN  OBTypeTable      ttab;
  EXTERN  OBIsotopeTable   isotab;
  EXTERN  OBAromaticTyper  aromtyper;
  EXTERN  OBAtomTyper      atomtyper;
  EXTERN  OBChainsParser   chainsparser;
  OBERROR extern  OBMessageHandler obErrorLog;
  EXTERN  OBResidueData    resdat;

  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