RDCode: Reaction.h Source File

# Reaction.h

Go to the documentation of this file.

    00001 //
    00002 //  Copyright (c) 2007, Novartis Institutes for BioMedical Research Inc.
    00003 //  All rights reserved.
    00004 //
    00005 // Redistribution and use in source and binary forms, with or without
    00006 // modification, are permitted provided that the following conditions are
    00007 // met:
    00008 //
    00009 //     * Redistributions of source code must retain the above copyright
    00010 //       notice, this list of conditions and the following disclaimer.
    00011 //     * Redistributions in binary form must reproduce the above
    00012 //       copyright notice, this list of conditions and the following
    00013 //       disclaimer in the documentation and/or other materials provided
    00014 //       with the distribution.
    00015 //     * Neither the name of Novartis Institutes for BioMedical Research Inc.
    00016 //       nor the names of its contributors may be used to endorse or promote
    00017 //       products derived from this software without specific prior written permission.
    00018 //
    00019 // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
    00020 // "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
    00021 // LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
    00022 // A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
    00023 // OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
    00024 // SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
    00025 // LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
    00026 // DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
    00027 // THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
    00028 // (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
    00029 // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    00030 //
    00031
    00032 #ifndef __RD_REACTION_H_17Aug2006__
    00033 #define __RD_REACTION_H_17Aug2006__
    00034
    00035 #include <GraphMol/RDKitBase.h>
    00036 #include <GraphMol/Substruct/SubstructMatch.h>
    00037 #include <vector>
    00038
    00039 namespace RDKit{
    00040
    00041   //! used to indicate an error in the chemical reaction engine
    00042   class ChemicalReactionException : public std::exception {
    00043   public:
    00044     //! construct with an error message
    00045     explicit ChemicalReactionException(const char *msg) : _msg(msg) {};
    00046     //! construct with an error message
    00047     explicit ChemicalReactionException(const std::string msg) : _msg(msg) {};
    00048     //! get the error message
    00049     const char *message () const { return _msg.c_str(); };
    00050     ~ChemicalReactionException () throw () {};
    00051   private:
    00052     std::string _msg;
    00053   };
    00054
    00055   //! This is a class for storing and applying general chemical reactions.
    00056   /*!
    00057      basic usage will be something like:
    00058
    00059      \verbatim
    00060      ChemicalReaction rxn;
    00061      rxn.addReactantTemplate(r1);
    00062      rxn.addReactantTemplate(r2);
    00063      rxn.addProductTemplate(p1);
    00064      rxn.initReactantMatchers();
    00065
    00066      MOL_SPTR_VECT prods;
    00067      for(MOL_SPTR_VECT::const_iterator r1It=reactantSet1.begin();
    00068          r1It!=reactantSet1.end();++r1It;){
    00069        for(MOL_SPTR_VECT::const_iterator r2It=reactantSet2.begin();
    00070            r2It!=reactantSet2.end();++r2It;){
    00071          MOL_SPTR_VECT rVect(2);
    00072          rVect[0] = *r1It;
    00073          rVect[1] = *r2It;
    00074
    00075          std::vector<MOL_SPTR_VECT> lprods;
    00076          lprods = rxn.runReactants(rVect);
    00077          for(std::vector<MOL_SPTR_VECT>::const_iterator lpIt=lprods.begin();
    00078             lpIt!=lprods.end();++lpIt){
    00079             // we know this is a single-product reaction:
    00080             prods.push_back((*lpIt)[0]);
    00081          }
    00082        }
    00083      }
    00084      \endverbatim
    00085
    00086   */
    00087   class ChemicalReaction {
    00088   public:
    00089     ChemicalReaction() : df_needsInit(true), df_implicitProperties(false) {};
    00090     ChemicalReaction(const ChemicalReaction &other){
    00091         df_needsInit=true;
    00092         df_implicitProperties=other.df_implicitProperties;
    00093         m_reactantTemplates=other.m_reactantTemplates;
    00094         m_productTemplates=other.m_productTemplates;
    00095     }
    00096     //! Adds a new reactant template
    00097     /*!
    00098       \return the number of reactants
    00099
    00100     */
    00101     unsigned int addReactantTemplate(ROMOL_SPTR mol){
    00102       this->df_needsInit = true;
    00103       this->m_reactantTemplates.push_back(mol);
    00104       return this->m_reactantTemplates.size();
    00105     }
    00106
    00107     //! Adds a new product template
    00108     /*!
    00109       \return the number of products
    00110
    00111     */
    00112     unsigned int addProductTemplate(ROMOL_SPTR mol){
    00113       this->m_productTemplates.push_back(mol);
    00114       return this->m_productTemplates.size();
    00115     }
    00116
    00117
    00118     //! Runs the reaction on a set of reactants
    00119     /*!
    00120
    00121       \param reactants: the reactants to be used. The length of this must be equal to
    00122                         this->getNumReactantTemplates()
    00123
    00124       \return a vector of vectors of products. Each subvector will be this->getNumProductTemplates()
    00125               long.
    00126
    00127       We return a vector of vectors of products because each individual template may map multiple times
    00128       onto its reactant. This leads to multiple possible result sets.
    00129     */
    00130     std::vector<MOL_SPTR_VECT> runReactants(const MOL_SPTR_VECT reactants) const;
    00131
    00132     MOL_SPTR_VECT::const_iterator beginReactantTemplates() const {
    00133         return this->m_reactantTemplates.begin();
    00134     }
    00135     MOL_SPTR_VECT::const_iterator endReactantTemplates() const {
    00136         return this->m_reactantTemplates.end();
    00137     }
    00138
    00139     MOL_SPTR_VECT::const_iterator beginProductTemplates() const {
    00140         return this->m_productTemplates.begin();
    00141     }
    00142     MOL_SPTR_VECT::const_iterator endProductTemplates() const {
    00143         return this->m_productTemplates.end();
    00144     }
    00145     unsigned int getNumReactantTemplates() const { return this->m_reactantTemplates.size(); };
    00146     unsigned int getNumProductTemplates() const { return this->m_productTemplates.size(); };
    00147
    00148     //! initializes our internal reactant-matching datastructures.
    00149     /*!
    00150         This must be called after adding reactants and before calling
    00151         runReactants.
    00152     */
    00153     void initReactantMatchers();
    00154
    00155     bool isInitialized() const { return !df_needsInit; };
    00156
    00157     //! validates the reactants and products to make sure the reaction seems "reasonable"
    00158     /*!
    00159         \return   true if the reaction validates without errors (warnings do not stop validation)
    00160
    00161         \param numWarnings: used to return the number of validation warnings
    00162         \param numErrors:   used to return the number of validation errors
    00163
    00164         \param silent: If this bool is true, no messages will be logged during the validation.
    00165                        By default, validation problems are reported to the warning and error
    00166                        logs depending on their severity.
    00167
    00168     */
    00169     bool validate(unsigned int &numWarnings,unsigned int &numErrors,bool silent=false) const;
    00170
    00171
    00172     //! returns whether or not the reaction uses implicit
    00173     //! properties on the product atoms
    00174     /*!
    00175
    00176       This toggles whether or not unspecified atomic properties in the
    00177       products are considered to be implicit and should be copied from
    00178       the actual reactants. This is necessary due to a semantic difference
    00179       between the "reaction SMARTS" approach and the MDL RXN
    00180       approach:
    00181         In "reaction SMARTS", this reaction:
    00182           [C:1]-[Br:2].[O-:3]>>[C:1]-[O:3].[Br-:2]
    00183         applied to [CH4+]Br should yield [CH4+]O
    00184         Something similar drawn in an rxn file, and applied to
    00185         [CH4+]Br should yield [CH3]O.
    00186         In rxn there is no charge on the product C because nothing is
    00187         specified in the rxn file; in "SMARTS" the charge from the
    00188         actual reactants is not *removed* because no charge is
    00189         specified in the reaction.
    00190
    00191     */
    00192     bool getImplicitPropertiesFlag() const { return df_implicitProperties; };
    00193     //! sets the implicit properties flag. See the documentation for
    00194     //! getImplicitProertiesFlag() for a discussion of what this means.
    00195     void setImplicitPropertiesFlag(bool val) { df_implicitProperties=val; };
    00196
    00197   private:
    00198     bool df_needsInit;
    00199     bool df_implicitProperties;
    00200     MOL_SPTR_VECT m_reactantTemplates,m_productTemplates;
    00201     ChemicalReaction &operator=(const ChemicalReaction &); // disable assignment
    00202     MOL_SPTR_VECT generateOneProductSet(const MOL_SPTR_VECT &reactants,const std::vector<MatchVectType> &reactantsMatch) const;
    00203   };
    00204
    00205 } // end of RDKit namespace
    00206
    00207 #endif