Package org.openscience.cdk.aromaticity

Class Aromaticity

  • public final class Aromaticity
extends Object
    A configurable model to perceive aromatic systems. Aromaticity is useful as both a chemical property indicating stronger stabilisation and as a way to treat different resonance forms as equivalent. Each has its own implications the first in physicochemical attributes and the second in similarity, depiction and storage. To address the resonance forms, several simplified (sometimes conflicting) models have arisen. Generally the models loosely follow Hückel's rule for determining aromaticity. A common omission being that planarity is not tested and chemical compounds which are non-planar can be perceived as aromatic. An example of one such compound is, cyclodeca-1,3,5,7,9-pentaene. Although there is not a single universally accepted model there are models which may better suited for a specific use (Cheminformatics Toolkits: A Personal Perspective, Roger Sayle). The different models are often ill-defined or unpublished but it is important to acknowledge that there are differences. Although models may get more complicated (e.g. considering tautomers) normally the reasons for differences are:
    • the atoms allowed and how many electrons each contributes
    • the rings/cycles are tested
    This implementation allows configuration of these via an ElectronDonation model and CycleFinder. To obtain an instance of the electron donation model use one of the constants:

    Recommended Usage:
    Which model/cycles to use depends on the situation but a good general purpose configuration is shown below which applies the model to all cycles/rings in a molecule using a backtracking search: 
    
 for (IAtomContainer molecule : molecules) {
     Cycles.markRingAtomsAndBonds(molecule);
     if (!Aromaticity.apply(Aromaticity.Model.CDX_2x, molecule)) {
         // molecule has v. complex rings! but aromaitcity
         // will still have been marked on small rings
     }
 }
    Alternative usage which throws an exception when the molecule is too complex: 
    
 ElectronDonation model       = ElectronDonation.CDK_2x;
 CycleFinder      cycles      = Cycles.all();
 Aromaticity      aromaticity = new Aromaticity(model, cycles);
 for (IAtomContainer molecule : molecules) {
   try {
      aromaticity.apply(molecule);
   } catch (CDKException ex) {
      // aromaticity failed, molecule to complex
   }
 }
    Author:
    John Mayfield
    See Also:
    Hückel's rule, Cheminformatics Toolkits: A Personal Perspective, Roger Sayle, Aromaticity Perception Differences, Blue Obelisk
    Source code:
    main
    Belongs to CDK module:
    standard

    • Constructor Detail

      • Aromaticity

        public Aromaticity​(ElectronDonation model,
                   CycleFinder cycles)
        Create an aromaticity model using the specified electron donation model which is tested on the cycles. The model defines how many π-electrons each atom may contribute to an aromatic system. The cycles defines the CycleFinder which is used to find cycles in a molecule. The total electron donation from each atom in each cycle is counted and checked. If the electron contribution is equal to 4n + 2 for a n >= 0 then the cycle is considered aromatic. Changing the electron contribution model or which cycles are tested affects which atoms/bonds are found to be aromatic. There are several ElectronDonation models and Cycles available. A good choice for the cycles is to use Cycles.all() falling back to Cycles.relevant() on failure. Finding all cycles is very fast but may produce an exponential number of cycles. It is therefore not feasible for complex fused systems and an exception is thrown. In such cases the aromaticity can either be skipped or a simpler polynomial cycle set Cycles.relevant() used. 
        
 // mimics the CDKHuckelAromaticityDetector
 Aromaticity aromaticity = new Aromaticity(ElectronDonation.cdk(),
                                           Cycles.cdkAromaticSet());

 // mimics the DoubleBondAcceptingAromaticityDetector
 Aromaticity aromaticity = new Aromaticity(ElectronDonation.cdkAllowingExocyclic(),
                                           Cycles.cdkAromaticSet());

 // a good model for writing SMILES
 Aromaticity aromaticity = new Aromaticity(ElectronDonation.daylight(),
                                           Cycles.all());

 // a good model for writing MDL/Mol2
 Aromaticity aromaticity = new Aromaticity(ElectronDonation.piBonds(),
                                           Cycles.all());
        Parameters:
        model - the model
        cycles - the cycles to apply it to
        See Also:
        ElectronDonation, Cycles

    • Method Detail

      • apply

        public static boolean apply​(ElectronDonation model,
                            IAtomContainer molecule)
        Apply an aromaticity model to all cycles/rings in a molecule up to the specified maxRingSize. This includes rings round the outside of a fused/bridged cycles (e.g. azulene). 
        
 Cycles.markRingAtomsAndBonds(molecule); // required!!
 if (!Aromaticity.apply(Aromaticity.Model.Daylight, molecule)) {
     // molecule had some v. complex rings in it!
 }
        The return value indicates if the model was applied full or not. Even if false is returned small rings will have been marked as aromatic. If is more an indication that there are some bonds of which it is not possible to know for sure if they should be marked as aromatic. Typical these molecules are often complex cage like systems with some saturated atoms, fully unsaturated molecules like fullerene actually run quickly. Setting a max ring size to something reasonable like 14 (3x fused 6 membered rings) avoids this issue.
        Parameters:
        model - the aromaticity model
        molecule - the molecule
        Returns:
        if the model could be fully applied (true) or if the computation was not possible (false)

      • apply

        public static boolean apply​(ElectronDonation model,
                            IAtomContainer molecule,
                            int maxRingSize)
        Apply an aromaticity model to all cycles/rings in a molecule up to the specified maxRingSize. This includes rings round the outside of a fused/bridged cycles (e.g. azulene). 
        
 Cycles.markRingAtomsAndBonds(molecule); // required!!
 if (!Aromaticity.apply(Aromaticity.Model.Daylight, molecule)) {
     // molecule had some v. complex rings in it!
 }
        The return value indicates if the model was applied full or not. Even if false is returned small rings will have been marked as aromatic. If is more an indication that there are some bonds of which it is not possible to know for sure if they should be marked as aromatic. Typical these molecules are often complex cage like systems with some saturated atoms, fully unsaturated molecules like fullerene actually run quickly. Setting a max ring size to something reasonable like 14 (3x fused 6 membered rings) avoids this issue.
        Parameters:
        model - the aromaticity model
        molecule - the molecule
        maxRingSize - max ring size to check (optional)
        Returns:
        if the model could be fully applied (true) or if the computation was not possible (false)

      • findBonds

        public Set<IBond> findBonds​(IAtomContainer molecule)
                     throws CDKException
        Find the bonds of a molecule which this model determined were aromatic. 
        
 Aromaticity aromaticity = new Aromaticity(ElectronDonation.cdk(),
                                           Cycles.all());
 IAtomContainer container = ...;
 try {
     Set<IBond> bonds          = aromaticity.findBonds(container);
     int        nAromaticBonds = bonds.size();
 } catch (CDKException e) {
     // cycle computation was intractable
 }
        Parameters:
        molecule - the molecule to apply the model to
        Returns:
        the set of bonds which are aromatic
        Throws:
        CDKException - a problem occurred with the cycle perception - one can retry with a simpler cycle set

      • apply

        public boolean apply​(IAtomContainer molecule)
              throws CDKException
        Apply this aromaticity model to a molecule. Any existing aromaticity flags are removed - even if no aromatic bonds were found. This follows the idea of applying an aromaticity model to a molecule such that the result is the same irrespective of existing aromatic flags. If you require aromatic flags to be preserved the findBonds(IAtomContainer) can be used to find bonds without setting any flags. 
         Aromaticity aromaticity = new Aromaticity(ElectronDonation.cdk(),
                                           Cycles.all());
 IAtomContainer container = ...;
 try {
     if (aromaticity.apply(container)) {
         //
     }
 } catch (CDKException e) {
     // cycle computation was intractable
 }
        Parameters:
        molecule - the molecule to apply the model to
        Returns:
        the model found the molecule was aromatic
        Throws:
        CDKException

      • clear

        public static void clear​(IAtomContainer mol)
        Clear all aromatic flags from the atoms/bonds and molecule.
        Parameters:
        mol - the molecule

      • cdkLegacy

        @Deprecated
public static Aromaticity cdkLegacy()
        Deprecated.
        Use a better aromaticity model
        Access an aromaticity instance that replicates the previously utilised - CDKHueckelAromaticityDetector. It has the following configuration: 
        
 new Aromaticity(ElectronDonation.cdk(),
                 Cycles.cdkAromaticSet());

        This model is not necessarily bad (or really considered legacy) but should not be considered a gold standard model that covers all possible cases. It was however the primary method used in previous versions of the CDK (1.4).

        This factory method is provided for convenience for those wishing to replicate aromaticity perception used in previous versions. The same electron donation model can be used to test aromaticity of more cycles. For instance, the following configuration will identify more bonds in a some structures as aromatic: 

        
 new Aromaticity(ElectronDonation.cdk(),
                 Cycles.or(Cycles.all(), Cycles.relevant()));
        Returns:
        aromaticity instance that is configured to perform identically to the primary aromaticity model in version 1.4.