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 factory methods, ElectronDonation.cdk(), ElectronDonation.cdkAllowingExocyclic(), ElectronDonation.daylight() or ElectronDonation.piBonds().

    Recommended Usage:
    Which model/cycles to use depends on the situation but a good general purpose configuration is shown below: 
     ElectronDonation model       = ElectronDonation.daylight();
 CycleFinder      cycles      = Cycles.or(Cycles.all(), Cycles.all(6));
 Aromaticity      aromaticity = new Aromaticity(model, cycles);

 // apply our configured model to each molecule
 for (IAtomContainer molecule : molecules) {
     aromaticity.apply(molecule);
 }
    Author:
    John May
    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 -
        cycles -
        See Also:
        ElectronDonation, Cycles

    • Method Detail

      • 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

      • cdkLegacy

        public static Aromaticity cdkLegacy()
        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.