Class ExtendedMolecule

  • All Implemented Interfaces:
    java.io.Serializable
    Direct Known Subclasses:
    StereoMolecule

    public class ExtendedMolecule
    extends Molecule
    implements java.io.Serializable
    While the Molecule class covers all primary molecule information as atom and bond properties, the atom connectivity and coordinates, its derived class ExtendedMolecule handles secondary, i.e. calculated molecule information. Most important are the directly connected atoms and bonds of every atom, information about rings and whether they are aromatic, and some atom properties that depend on their near neighbors. This calculated information is cached in helper arrays and stays valid as long as the molecule's primary information is not changed. High level methods, e.g. getPath(), that require valid helper arrays take care of updating the cache themselves. Low level methods, e.g. isAromaticAtom(), which typically are called very often, do not check the validity of or update the helper arrays themselves for performance reasons. If you use low level methods, then you need to make sure that the required helper array information is valid by calling ensureHelperArrays(). Typically you will never instantiate an ExtendedMolecule, but rather use a StereoMolecule.
    See Also:
    Serialized Form
    • Field Detail

      • FISCHER_PROJECTION_LIMIT

        public static final float FISCHER_PROJECTION_LIMIT
        To interpret a stereo center as fisher projection, all non stereo bonds must be vertical and all stereo bonds must be horizontal. FISCHER_PROJECTION_LIMIT is the allowed tolerance (currently 5.0 degrees). In addition in large rings we don't assume Fisher projections, because coordinates, if just in a circle, may have subsequent almost vertical bonds.
        See Also:
        Constant Field Values
      • FISCHER_PROJECTION_RING_LIMIT

        public static final float FISCHER_PROJECTION_RING_LIMIT
        See Also:
        Constant Field Values
    • Constructor Detail

      • ExtendedMolecule

        public ExtendedMolecule()
      • ExtendedMolecule

        public ExtendedMolecule​(int maxAtoms,
                                int maxBonds)
      • ExtendedMolecule

        public ExtendedMolecule​(Molecule mol)
    • Method Detail

      • copyMoleculeByAtoms

        public void copyMoleculeByAtoms​(ExtendedMolecule destMol,
                                        boolean[] includeAtom,
                                        boolean recognizeDelocalizedBonds,
                                        int[] atomMap)
        Clears destmol and then copies a part of this Molecule into destMol, being defined by a mask of atoms to be included. If not all atoms are copied, then destMol is set to be a substructure fragment.
        Parameters:
        destMol - receives the part of this Molecule
        includeAtom - defines atoms to be copied; its size may be this.getAtoms() or this.getAllAtoms()
        recognizeDelocalizedBonds - defines whether disconnected delocalized bonds will keep their single/double bond status or whether the query feature 'delocalized bond' will be set
        atomMap - null or int[] not smaller than includeAtom.length; receives atom indices of dest molecule or -1 if not copied
      • copyMoleculeByBonds

        public int[] copyMoleculeByBonds​(ExtendedMolecule destMol,
                                         boolean[] includeBond,
                                         boolean recognizeDelocalizedBonds,
                                         int[] atomMap)
        Clears destmol and then copies a part of this Molecule into destMol, being defined by a mask of bonds to be included. Bonds, whose atoms carry opposite charges are treated in the following manner: If only one of the two bond atoms is kept, then its absolute charge will be reduced by 1.
        Parameters:
        destMol - receives the part of this Molecule
        includeBond - defines bonds to be copied
        recognizeDelocalizedBonds - defines whether disconnected delocalized bonds will keep their single/double bond status or whether the query feature 'delocalized bond' will be set
        atomMap - null or int[] not smaller than this.getAllAtoms()
        Returns:
        atom map from this to destMol with not copied atom's index being -1
      • getAllConnAtoms

        public int getAllConnAtoms​(int atom)
        The neighbours (connected atoms) of any atom are sorted by their relevance:
        1. non-hydrogen atoms (bond order 1 and above) and unusual hydrogen atoms (non natural abundance isotops, custom labelled hydrogen, etc.)
        2. plain-hydrogen atoms (natural abundance, bond order 1)
        3. loosely connected atoms (bond order 0, i.e. metal ligand bond)
        Only valid after calling ensureHelperArrays(cHelperNeighbours or higher);
        Parameters:
        atom -
        Returns:
        count of category 1 & 2 neighbour atoms (excludes neighbours connected with zero bond order)
      • getPlainHydrogens

        public int getPlainHydrogens​(int atom)
        Parameters:
        atom -
        Returns:
        the number of connected plain explicit and implicit hydrogen atoms (does not include 2H,3H, custom labelled H)
      • getAllHydrogens

        public int getAllHydrogens​(int atom)
        Parameters:
        atom -
        Returns:
        the number of connected explicit and implicit hydrogen atoms (includes 2H,3H, custom labelled H)
      • getAtoms

        public int getAtoms()
        A validated molecule (after helper array creation) contains a sorted list of all atoms with the plain (neglegible) hydrogen atoms at the end of the list. Neglegible hydrogen atoms a those that can be considered implicit, because they have no attached relevant information. Hydrogen atoms that cannot be neglected are special isotops (mass != 0), if they carry a custom label, if they are connected to another atom with bond order different from 1, or if they are connected to another neglegible hydrogen.
        Only valid after calling ensureHelperArrays(cHelperNeighbours or higher);
        Returns:
        the number of relevant atoms not including neglegible hydrogen atoms
      • getMetalBondedConnAtoms

        public int getMetalBondedConnAtoms​(int atom)
        Parameters:
        atom -
        Returns:
        count of neighbour atoms connected by a 0-order metal ligand bond
      • getAtomPi

        public int getAtomPi​(int atom)
        This is different from the Hendrickson pi-value, which considers pi-bonds to carbons only.
        Parameters:
        atom -
        Returns:
        the number pi electrons at atom (the central atom of acetone would have 1)
      • getAtomRingSize

        public int getAtomRingSize​(int atom)
        Parameters:
        atom -
        Returns:
        0 or the size of the smallest ring that atom is a member of
      • getBondRingSize

        public int getBondRingSize​(int bond)
        Parameters:
        bond -
        Returns:
        0 or the size of the smallest ring that bond is a member of
      • getBonds

        public int getBonds()
        The bond list is preprocessed such that all bonds leading to a plain hydrogen atom (natural abundance, no custom labels) are at the end of the list. Only valid after calling ensureHelperArrays(cHelperNeighbours or higher);
        Returns:
        count of bonds not including those connecting plain-H atoms
      • getBond

        public int getBond​(int atom1,
                           int atom2)
        Returns:
        -1 or the bond that connects atom1 with atom2
      • getCompactCopy

        public ExtendedMolecule getCompactCopy()
        Returns:
        a copy of this with all arrays sized to just cover all existing atoms and bonds
      • getConnAtom

        public int getConnAtom​(int atom,
                               int i)
        The neighbours (connected atoms) of any atom are sorted by their relevance:
        1. non-hydrogen atoms (bond order 1 and above) and unusual hydrogen atoms (non natural abundance isotops, custom labelled hydrogen, etc.)
        2. plain-hydrogen atoms (natural abundance, bond order 1)
        3. loosely connected atoms (bond order 0, i.e. metall ligand bond)
        Only valid after calling ensureHelperArrays(cHelperNeighbours or higher);
        Parameters:
        atom -
        i - index into sorted neighbour list
        Returns:
        the i-th neighbor atom of atom
      • getConnAtoms

        public int getConnAtoms​(int atom)
        The neighbours (connected atoms) of any atom are sorted by their relevance:
        1. non-hydrogen atoms (bond order 1 and above) and unusual hydrogen atoms (non natural abundance isotops, custom labelled hydrogen, etc.)
        2. plain-hydrogen atoms (natural abundance, bond order 1)
        3. loosely connected atoms (bond order 0, i.e. metall ligand bond)
        Only valid after calling ensureHelperArrays(cHelperNeighbours or higher);
        Parameters:
        atom -
        Returns:
        count of category 1 neighbour atoms (excludes plain H and bond zero orders)
      • getAllConnAtomsPlusMetalBonds

        public int getAllConnAtomsPlusMetalBonds​(int atom)
        The neighbours (connected atoms) of any atom are sorted by their relevance:
        1. non-hydrogen atoms (bond order 1 and above) and unusual hydrogen atoms (non natural abundance isotops, custom labelled hydrogen, etc.)
        2. plain-hydrogen atoms (natural abundance, bond order 1)
        3. loosely connected atoms (bond order 0, i.e. metall ligand bond)
        Only valid after calling ensureHelperArrays(cHelperNeighbours or higher);
        Parameters:
        atom -
        Returns:
        count of category 1 & 2 & 3 neighbour atoms
      • getConnBond

        public int getConnBond​(int atom,
                               int i)
        The neighbours (connected atoms) of any atom are sorted by their relevance:
        1. non-hydrogen atoms (bond order 1 and above) and unusual hydrogen atoms (non natural abundance isotops, custom labelled hydrogen, etc.)
        2. plain-hydrogen atoms (natural abundance, bond order 1)
        3. loosely connected atoms (bond order 0, i.e. metall ligand bond)
        Only valid after calling ensureHelperArrays(cHelperNeighbours or higher);
        Parameters:
        atom -
        i - index into sorted neighbour list
        Returns:
        index of bond connecting atom with its i-th neighbor
      • getConnBondOrder

        public int getConnBondOrder​(int atom,
                                    int i)
        The neighbours (connected atoms) of any atom are sorted by their relevance:
        1. non-hydrogen atoms (bond order 1 and above) and unusual hydrogen atoms (non natural abundance isotops, custom labelled hydrogen, etc.)
        2. plain-hydrogen atoms (natural abundance, bond order 1)
        3. loosely connected atoms (bond order 0, i.e. metall ligand bond)
        Only valid after calling ensureHelperArrays(cHelperNeighbours or higher); Orders of delocalized bonds, i.e. bonds in an aromatic 6-membered ring, are returned as 1.
        Parameters:
        atom -
        i - index into sorted neighbour list
        Returns:
        order of bond connecting atom with its i-th neighbor
      • getNonHydrogenNeighbourCount

        public int getNonHydrogenNeighbourCount​(int atom)
        This method returns the non-hydrogen neighbour count of atom. It excludes any hydrogen atoms in contrast to getConnAtoms(), which only excludes plain hydrogen (not deuterium, tritium, custom labelled hydrogen, etc.). Don't use this method's return value for loops with getConnAtom(), getConnBond(), or getConnBondOrder().
        Parameters:
        atom -
        Returns:
        the number of non-hydrogen neighbor atoms
      • getExcludedNeighbourCount

        public int getExcludedNeighbourCount​(int atom)
        This method returns the count of atom neighbours which are marked as being an exclude group.
        Parameters:
        atom -
        Returns:
        the number of non-hydrogen neighbor atoms
      • getAverageBondLength

        public double getAverageBondLength​(boolean nonHydrogenBondsOnly)
        Calculates and returns the mean bond length of all bonds including or not including hydrogen bonds. If there are no bonds, then the average distance between unconnected atoms is returned. If we have less than 2 atoms, cDefaultAverageBondLength is returned.
        Parameters:
        nonHydrogenBondsOnly -
        Returns:
      • getOccupiedValence

        public int getOccupiedValence​(int atom)
        The sum of bond orders of explicitly connected neighbour atoms including explicit hydrogen. In case of a fragment the occupied valence does not include bonds to atoms of which the cAtomQFExcludeGroup flag is set. Atom charge and radical states are not considered.
        Overrides:
        getOccupiedValence in class Molecule
        Parameters:
        atom -
        Returns:
        explicitly used valence
      • getFreeValence

        public int getFreeValence​(int atom)
        The free valence is the number of potential additional single bonded neighbours to reach the atom's maximum valence. Atomic numbers that have multiple possible valences, the highest value is taken. Atom charges are considered. Implicit hydrogens are not considered. Thus, the oxygen in a R-O(-) has a free valence of 0, the nitrogen in R3N(+) has a free valence of 1. Chlorine in Cl(-) has a free valence of 6. If you need the free valence taking the lowest possible valence into account, use getLowestFreeValence(), which would return 0 for Cl(-).
        Parameters:
        atom -
        Returns:
      • getLowestFreeValence

        public int getLowestFreeValence​(int atom)
        The lowest free valence is the number of potential additional single bonded neighbours to reach the atom's lowest valence above or equal its current occupied valence. Atom charges are considered. Implicit hydrogens are not considered. Thus, the phosphor atoms in PF2 and PF4 both have a lowest free valence of 1. The oxygen in R-O(-) has a lowest free valence of 0, the nitrogen in R3N(+) has a free valence of 1. If you need the maximum possible free valence, use getFreeValence(), which would give 6 for Cl(-) and HCl.
        Parameters:
        atom -
        Returns:
      • getImplicitHigherValence

        public int getImplicitHigherValence​(int atom,
                                            boolean neglectExplicitHydrogen)
        If the explicitly attached neighbors cause an atom valence to exceed the lowest allowed valence for this atomic no, then this method returns the next higher allowed valence, e.g. O=P(-H)-OMe :
        standard P valence is 3, used valence is 4, implicit abnormal valence is 5. The molecule is interpreted as O=PH2-OMe. Requires cHelperNeighbours!
        Parameters:
        atom -
        neglectExplicitHydrogen -
        Returns:
        abnormal valence or -1 if valence doesn't exceed standard valence
      • getAverageTopologicalAtomDistance

        public float[] getAverageTopologicalAtomDistance()
        Calculates for every non-H atom the mean value of all shortest routes (bonds in between) to any other atom of the same fragment.
        Returns:
      • getPathLength

        public int getPathLength​(int atom1,
                                 int atom2)
        Calculates the length of the shortest path between atoms atom1 and atom2
        Parameters:
        atom1 -
        atom2 -
        Returns:
        path length (no of bonds); -1 if there is no path
      • getPathLength

        public int getPathLength​(int atom1,
                                 int atom2,
                                 int maxLength,
                                 boolean[] neglectAtom)
        Calculates the length of the shortest path between atoms atom1 and atom2, which is not larger than maxLength and avoids atoms indicated by neglectAtom.
        Parameters:
        atom1 -
        atom2 -
        maxLength - paths larger than maxLength won't be detected
        neglectAtom - null or atoms flagged which are forbidden path members
        Returns:
        path length (no of bonds); -1 if there is no path
      • getPath

        public int getPath​(int[] pathAtom,
                           int atom1,
                           int atom2,
                           int maxLength,
                           boolean[] neglectBond)
        Locates and returns the shortest path between atoms atom1 and atom2
        Parameters:
        pathAtom - array large enough to hold all path atoms, i.e. maxLength+1
        atom1 - first atom of path; ends up in pathAtom[0]
        atom2 - last atom of path; ends up in pathAtom[pathLength]
        maxLength - paths larger than maxLength won't be detected
        neglectBond - null or bitmask of forbidden bonds
        Returns:
        number of bonds of path; -1 if there is no path
      • getPathBonds

        public void getPathBonds​(int[] pathAtom,
                                 int[] pathBond,
                                 int pathLength)
        Finds bonds of a path that is defined by an atom sequence.
        Parameters:
        pathAtom - pathAtom[0]...[pathLength] -> list of atoms on path
        pathBond - int array not smaller than pathLength
        pathLength - no of path bonds == no of path atoms - 1
      • shareSameFragment

        public boolean shareSameFragment​(int atom1,
                                         int atom2)
        Parameters:
        atom1 -
        atom2 -
        Returns:
        whether there is a path of bonds leading from atom1 to atom2
      • addFragment

        public void addFragment​(ExtendedMolecule sourceMol,
                                int rootAtom,
                                int[] atomMap)
        This adds a fragment from sourceMol to this molecule by first copying rootAtom and then all connected atoms and bonds by traversing the graph breadth first.
        Parameters:
        sourceMol - molecule from which the fragment is copied to this
        rootAtom -
        atomMap - null or int[] not smaller than sourceMol.mAllAtoms; receives atom indices of this molecule
      • getFragmentAtoms

        public int[] getFragmentAtoms​(int rootAtom)
        Returns an array of all atoms for which a path of bonds leads to rootAtom not considering metal ligand bonds.
        Parameters:
        rootAtom -
        Returns:
        atoms being in the same fragment as rootAtom
      • getFragmentAtoms

        public int[] getFragmentAtoms​(int rootAtom,
                                      boolean considerMetalBonds)
        Returns an array of all atoms for which a path of bonds leads to rootAtom. Metal ligand bonds may or may not be considered a connection.
        Parameters:
        rootAtom -
        considerMetalBonds -
        Returns:
        atoms being in the same fragment as rootAtom
      • getFragmentNumbers

        public int getFragmentNumbers​(int[] fragmentNo,
                                      boolean[] neglectBond,
                                      boolean considerMetalBonds)
        Locates all disconnected fragments in the molecule and assigns fragment numbers (starting from 0) to all atoms. Individual bonds can be marked to be skipped, i.e. to be treated as non-existing. Metal ligand bonds may or may not be considered a connection.
        Parameters:
        fragmentNo - array not smaller than getAllAtoms()
        neglectBond - array not smaller than getAllBonds()
        considerMetalBonds -
        Returns:
        array of atom's fragments indexes
      • getFragmentNumbers

        public int getFragmentNumbers​(int[] fragmentNo,
                                      boolean markedAtomsOnly,
                                      boolean considerMetalBonds)
        Locates all unconnected fragments in the Molecule and assigns fragment indexes for every atom starting with 0. Optionally the fragment detection may be restricted to those atoms that have been previously marked with setAtomMarker(). In that case non-marked atoms receive the fragment number -1 and are not considered a connection between marked atoms potentially causing two marked atoms to end up in different fragments, despite sharing the same fragment. Metal ligand bonds may or may not be considered a connection.
        Parameters:
        fragmentNo - array at least mAllAtoms big to receive atom fragment indexes
        markedAtomsOnly - if true, then only atoms marked with setAtomMarker() are considered
        considerMetalBonds -
        Returns:
        number of disconnected fragments
      • stripSmallFragments

        public int[] stripSmallFragments()
        Removes all unconnected fragments except for the largest one. If small fragments were removed, then canonizeCharge() is called to neutralize charges after potential removal of counter ions. Metal ligand bonds are not considered a connection.
        Returns:
        atom mapping from old to new index; null if no fragments were removed
      • stripSmallFragments

        public int[] stripSmallFragments​(boolean considerMetalBonds)
        Removes all unconnected fragments except for the largest one. If small fragments were removed, then canonizeCharge() is called to neutralize charges after potential removal of counter ions. Metal ligand bonds may or may not be considered a connection.
        Parameters:
        considerMetalBonds -
        Returns:
        atom mapping from old to new index; null if no fragments were removed
      • findRingSystem

        public void findRingSystem​(int startAtom,
                                   boolean aromaticOnly,
                                   boolean[] isMemberAtom,
                                   boolean[] isMemberBond)
        Starting from startAtom this method locates a system of annelated or bridged ring systems with all members bonds being a ring bond. Detected member atoms and bonds are flagged accordingly.
        Parameters:
        startAtom -
        aromaticOnly - if set then only aromatic atoms and bonds are considered
        isMemberAtom -
        isMemberBond -
      • getSubstituent

        public int getSubstituent​(int coreAtom,
                                  int firstAtom,
                                  boolean[] isMemberAtom,
                                  ExtendedMolecule substituent,
                                  int[] atomMap)
        Determines all atoms of the substituent attached to coreAtom and starting with firstAtom. If isMemberAtom!=null, then all substituent member atoms will have the the respective index being flagged upon return. This includes firstAtom and excludes coreAtom. If substituent!=null, then it will contain the substituent as Molecule. At the position of the coreAtom substituent will contain a wildcard atom. If substituent!=null and atomMap!=null then atomMap receives atom index mapping from this to substituent with non-member atoms being -1. Returns -1 and an empty substituent if coreAtom and firstAtom share a ring
        Parameters:
        coreAtom - the atom to which the substituent is connected
        firstAtom - the substituent's atom that is connected to coreAtom
        isMemberAtom - may be null, otherwise set to contain atom membership mask
        substituent - may be null, otherwise set to contain the substituent
        atomMap - null or int[] not smaller than this.getAllAtoms()
        Returns:
        substituent atom count not counting coreAtom; -1 if coreAtom and firstAtom share a ring
      • getSubstituentSize

        public int getSubstituentSize​(int coreAtom,
                                      int firstAtom)
        Counts the number of atoms of the substituent connected to coreAtom defined by firstAtom and not including the coreAtom.
        Parameters:
        coreAtom -
        firstAtom -
        Returns:
        atom count of substituent or -1 if coreAtom and firstAtom are in the same ring
      • supportsImplicitHydrogen

        public boolean supportsImplicitHydrogen​(int atom)
        Whether an atom may be considered to carry implicit hydrogen atoms depends on the atomicNo of that atom. Aluminum and all non/metal atoms except the nobel gases and except hydrogen itself are considered to carry implicit hydrogens to fill up their unoccupied valences. Atoms with an assigned unusual valence always support implicit hydrogens independent of their atomicNo.
        Parameters:
        atom -
        Returns:
        true if this atom's unoccupied valences are considered to be implicit hydrogens
      • getImplicitHydrogens

        public int getImplicitHydrogens​(int atom)
        Calculates and return the number of implicit hydrogens at atom. If atom is itself a hydrogen atom, a metal except Al, or a noble gas, then 0 is returned. For all other atom kinds the number of implicit hydrogens is basically the lowest typical valence that is compatible with the occupied valence, minus the occupied valence corrected by atom charge and radical state.
        Parameters:
        atom -
        Returns:
      • getExplicitHydrogens

        public int getExplicitHydrogens​(int atom)
        Parameters:
        atom -
        Returns:
        number of explicit plain hydrogen atoms (does not include 2H, 3H, custom labelled H, etc)
      • getMolweight

        public int getMolweight()
        Calculates a rounded mass of the molecule
        Returns:
      • getRotatableBondCount

        public int getRotatableBondCount()
        Simple method to calculate rotatable bonds. This method counts all single bonds provided that they
        - are not a terminal bond
        - are not part of a ring
        - are not an amide bond
        - are not the second of two equivalent bonds next to the same triple bond
        Returns:
      • isPseudoRotatableBond

        public boolean isPseudoRotatableBond​(int bond)
        In a consecutive sequence of sp-hybridized atoms multiple single bonds cause redundant torsions. Only that single bond with the smallest bond index is considered really rotatable; all other single bonds are pseudo rotatable. If one/both end(s) of the sp-atom sequence doesn't carry atoms outside of the straight line then no bond is considered rotatable. A simple terminal single bond
        Parameters:
        bond -
        Returns:
        true, if this bond is not considered rotatable because of a redundancy
      • getAromaticRingCount

        public int getAromaticRingCount()
      • getAtomRingCount

        public int getAtomRingCount​(int atom,
                                    int maxRingSize)
        Calculates the number of independent rings of which 'atom' is a member. Any combination of two connected atoms to 'atom' is used for: - finding the shortest path connecting these two neighbors avoiding 'atom' - if such a path exists and at least one bonds of that path is not a member of a path found earlier then count this path as an independent ring closure.
        Parameters:
        atom -
        maxRingSize -
        Returns:
        number of independent rings
      • getRingSet

        public RingCollection getRingSet()
        Returns:
        a RingCollection object, which contains a total set of small rings
      • getRingSetSimple

        public RingCollection getRingSetSimple()
        Returns:
        a RingCollection object without aromaticity information
      • getAtomPreferredStereoBond

        public int getAtomPreferredStereoBond​(int atom)
        Locates that single bond which is the preferred one to be converted into up/down bond in order to define the atom chirality.
        Parameters:
        atom - parity carrying atom, i.e. a tetrahedral stereocenter or central allene atom
        Returns:
        preferred bond or -1, if no single bond existing
      • getBondPreferredStereoBond

        public int getBondPreferredStereoBond​(int bond)
        Locates that single bond which is the preferred one to be converted into up/down bond in order to define the bond chirality.
        Parameters:
        bond - BINAP type of chirality bond
        Returns:
        preferred bond or -1, if no single bond existing
      • isAllylicAtom

        public boolean isAllylicAtom​(int atom)
        Parameters:
        atom -
        Returns:
        whether the atom is in an allylic/benzylic position
      • isAromaticAtom

        public boolean isAromaticAtom​(int atom)
      • isAromaticBond

        public boolean isAromaticBond​(int bnd)
      • isDelocalizedBond

        public boolean isDelocalizedBond​(int bond)
        A bond is considered delocalized, if it has different bond orders in different, but energetically equivalent mesomeric structures. Bonds in aromatic 6-membered rings typically are delocalized, while those in uncharged 5-membered aromatic rings are not. Indole has 6 delocalized bonds.
        Parameters:
        bond -
        Returns:
      • isRingAtom

        public boolean isRingAtom​(int atom)
      • isRingBond

        public boolean isRingBond​(int bnd)
      • isSmallRingAtom

        public boolean isSmallRingAtom​(int atom)
        Parameters:
        atom -
        Returns:
        whether atom is a member of a ring not larger than 7 atoms
      • isSmallRingBond

        public boolean isSmallRingBond​(int bond)
        Parameters:
        bond -
        Returns:
        whether bond is a member of a ring not larger than 7 atoms
      • isStabilizedAtom

        public boolean isStabilizedAtom​(int atom)
        Parameters:
        atom -
        Returns:
        whether atom has a neighbor that is connected through a double/triple bond to a hetero atom
      • getAtomRingBondCount

        public int getAtomRingBondCount​(int atom)
      • getChiralText

        public java.lang.String getChiralText()
      • getStereoBond

        public int getStereoBond​(int atom)
        Checks whether at least one of the connected bonds is a stereo bond. If atom is the central atom of an allene, then its direct neighbours are checked, whether one of them has a stereo bond.
        Parameters:
        atom -
        Returns:
        the stereo bond or -1 if not found
      • setParitiesValid

        public void setParitiesValid​(int helperStereoBits)
        Atom stereo parities and bond E/Z-parities are properties that are usually perceived from up/down-bonds and atom coordinates, respectively. This is done during the helper array calculation triggered by ensureHelperArrays(cHelperParities).
        This method tells the molecule that current atom/bond parities are valid, even if the stereo perception not has been performed. In addition to the stereo parities one may declare CIP parities and/or symmetry ranks also to be valid (helperStereoBits != 0). setParitiesValid(0) should be called if no coordinates are available but the parities are valid nevertheless, e.g. after the IDCodeParser has parsed an idcode without coordinates. (Note: After idcode parsing unknown stereo centers have parities cAtomParityNone instead of cAtomParityUnknown. Thus, calling isStereoCenter(atom) returns false!!!) Declaring parities valid prevents the Canonizer to run the stereo recognition again when ensureHelperArrays(cHelperParities or higher) is called.
        May also be called after filling valences with explicit hydrogen atoms, which have no coordinates, to tell the molecule that the earlier created stereo flags are still valid.
        Parameters:
        helperStereoBits - 0 or combinations of cHelperBitCIP,cHelperBitSymmetry...,cHelperBitIncludeNitrogenParities
      • setStereoBondsFromParity

        public void setStereoBondsFromParity()
        This converts one single bond per parity into a stereo up/down bond to correctly reflect the given parity. This works for tetrahedral and allene atom parities as well as for BINAP type of bond parities. Should only be called with valid TH and EZ parities and valid coordinates, e.g. after idcode parsing with coordinates or after coordinate generation.
      • convertStereoBondsToSingleBonds

        public void convertStereoBondsToSingleBonds​(int atom)
        Converts any stereo bond being attached with the pointed tip to the given potential stereocenter (TH or allene) into a single bond. For allenic stereo centers, stereo bonds at the allene end atoms are converted. Atoms with PI electrons are not touched, unless they are P,S,...
        Parameters:
        atom -
      • setStereoBondFromAtomParity

        public void setStereoBondFromAtomParity​(int atom)
      • getFisherProjectionParity

        public int getFisherProjectionParity​(int atom,
                                             int[] sortedConnMap,
                                             double[] angle,
                                             int[] direction)
        If the atom is a stereo center in fisher projection, then its tetrahedral parity is returned. If the horizontal bonds are plain single bonds, then they are interpreted as up-bonds.
        Parameters:
        atom - the stereo center
        sortedConnMap - map of neighbours sorted by atom index
        angle - bond angles sorted by neighbour atom index
        direction - null or int[] large enough to receive bond directions
        Returns:
        cAtomParity1,cAtomParity2 or cAtomParityUnknown
      • setStereoBondFromBondParity

        public void setStereoBondFromBondParity​(int bond)
        In case bond is a BINAP kind of chiral bond with defined parity, then the preferred neighbour single bond is converted into a stereo bond to correctly reflect its defined parity.
        Parameters:
        bond -
      • bondsAreParallel

        protected boolean bondsAreParallel​(double angle1,
                                           double angle2)
      • findAlleneCenterAtom

        public int findAlleneCenterAtom​(int atom)
        If atom is one of the two ends of an allene then returns allene center atom.
        Parameters:
        atom -
        Returns:
        allene center or -1
      • findAlleneEndAtom

        public int findAlleneEndAtom​(int atom1,
                                     int atom2)
        Crawls along a chain of sp-hybridized atoms starting from atom2 (which may not be sp-hybridized) away from its sp-hybridized neighbour atom1. Returns the first atom that is either not sp-hybridized anymore or the last atom of the chain if that is still sp-hybridized. Returns -1 in case of an sp-hybridized cycle.
        Parameters:
        atom1 - sp-hybridized atom
        atom2 - neighbour atom of atom1
        Returns:
        first non-sp-hybridized atom when crawling from atom2 away from atom1
      • findBINAPChiralityBond

        public int findBINAPChiralityBond​(int atom)
        Checks whether atom is one of the two atoms of an axial chirality bond of BINAP type. Condition: non-aromatic single bond connecting two aromatic rings with 6 or more members that together bear at least three ortho substituents. A stereo bond indicating the chirality is not(!!!) a condition.
        Parameters:
        atom - to check, whether it is part of a bond, which has BINAP type of axial chirality
        Returns:
        axial chirality bond or -1 if axial chirality conditions are not met
      • isAmideTypeBond

        public boolean isAmideTypeBond​(int bond)
        Evaluates, whether bond is an amide bond, thio-amide, or amidine bond.
        Parameters:
        bond -
        Returns:
      • isCentralAlleneAtom

        public boolean isCentralAlleneAtom​(int atom)
        Parameters:
        atom -
        Returns:
        whether this atom is the central atom of an allene
      • isFlatNitrogen

        public boolean isFlatNitrogen​(int atom)
        Checks whether this nitrogen atom is flat, because it has a double bond, is member of an aromatic ring or is part of amide, an enamine or in resonance with an aromatic ring. It is also checked that ortho substituents don't force the amine into a non-resonance torsion. State of helper arrays must be at least cHelperRings.
        Parameters:
        atom -
        Returns:
      • isBINAPChiralityBond

        public boolean isBINAPChiralityBond​(int bond)
        Checks whether bond is an axial chirality bond of the BINAP type. Condition: non-aromatic, non-small-ring (<= 7 members) single bond connecting two aromatic rings with 6 or more members each that together bear at least three ortho substituents. A stereo bond indicating the chirality is not(!!!) a condition.
        Parameters:
        bond -
        Returns:
        true if axial chirality conditions are met
      • validateBondType

        protected boolean validateBondType​(int bond,
                                           int type)
        Overrides:
        validateBondType in class Molecule
      • validate

        public void validate()
                      throws java.lang.Exception
        Throws:
        java.lang.Exception
      • normalizeAmbiguousBonds

        public boolean normalizeAmbiguousBonds()
        Normalizes different forms of functional groups (e.g. nitro) to a preferred one. This step should precede any canonicalization.
        Returns:
        true if the molecule was changed
      • isAlkaliMetal

        public boolean isAlkaliMetal​(int atom)
        Parameters:
        atom -
        Returns:
        whether atom is one of Li,Na,K,Rb,Cs
      • isEarthAlkaliMetal

        public boolean isEarthAlkaliMetal​(int atom)
        Parameters:
        atom -
        Returns:
        whether atom is one of Mg,Ca,Sr,Ba
      • isNitrogenFamily

        public boolean isNitrogenFamily​(int atom)
        Parameters:
        atom -
        Returns:
        whether atom is one of N,P,As
      • isChalcogene

        public boolean isChalcogene​(int atom)
        Parameters:
        atom -
        Returns:
        whether atom is one of O,S,Se,Te
      • isHalogene

        public boolean isHalogene​(int atom)
        Parameters:
        atom -
        Returns:
        whether atom is one of F,Cl,Br,I
      • canonizeCharge

        public int canonizeCharge​(boolean allowUnbalancedCharge)
                           throws java.lang.Exception
        Normalizes charge distribution in single- and multifragment molecules. In a first step polar bonds (both atoms have opposite charge) are neutralized by removing both atom charges and increasing the bond order, provided that atom valences allow the change. Neutralizes positive and an equal amount of negative charges on electronegative atoms, provided these are not on 1,2-dipolar structures, in order to ideally achieve a neutral molecule. This method does not change the overall charge of the molecule. It does not change the number of explicit atoms or bonds or their connectivity except bond orders. This method does not deprotonate acidic groups to compensate for quarternary charged nitrogen.
        Parameters:
        allowUnbalancedCharge - throws an exception after polar bond neutralization, if overall charge is not zero
        Returns:
        remaining overall molecule charge
        Throws:
        java.lang.Exception
      • canonizeCharge

        public int canonizeCharge​(boolean allowUnbalancedCharge,
                                  boolean doNeutralize)
                           throws java.lang.Exception
        Normalizes charge distribution in single- and multifragment molecules. In a first step polar bonds (both atoms have opposite charge) are neutralized by removing both atom charges and increasing the bond order, provided that atom valences allow the change. Neutralizes positive and an equal amount of negative charges on electronegative atoms, provided these are not on 1,2-dipolar structures, in order to ideally achieve a neutral molecule. This method may change the overall charge of the molecule if doNeutralize==true. It does not change the number of explicit atoms or bonds or their connectivity except bond orders. This method does not deprotonate acidic groups to compensate for quarternary charged nitrogen.
        Parameters:
        allowUnbalancedCharge - throws an exception after polar bond neutralization, if overall charge is not zero
        doNeutralize - if true, then tries to neutralize the molecule if overall charges are not zero
        Returns:
        remaining overall molecule charge
        Throws:
        java.lang.Exception
      • getZNeighbour

        public int getZNeighbour​(int connAtom,
                                 int bond)
        Provided that the bond parity of a double bond is available, this method determines, whether connAtom has a counterpart with Z- (cis) configuration at the other end of the double bond. If there is no Z-counterpart, then -1 is returned. Requires cHelperParities.
        Parameters:
        connAtom - directly connected to one of the double bond atoms
        bond - double bond with available bond parity
        Returns:
        -1 or counterpart to connAtom in Z-configuration
      • getHelperArrayStatus

        public int getHelperArrayStatus()
      • ensureHelperArrays

        public void ensureHelperArrays​(int required)
        While the Molecule class covers all primary molecule information, its derived class ExtendedMolecule handles secondary, i.e. calculated molecule information, which is cached in helper arrays and stays valid as long as the molecule's primary information is not changed. Most methods of ExtendedMolecule require some of the helper array's information. High level methods, e.g. getPath(), take care of updating an outdated cache themselves. Low level methods, e.g. isAromaticAtom(), which typically are called very often, do not check for validity nor update the helper arrays themselves. If you use low level methods, then you need to make sure that the needed helper array information is valid by this method.
        For performance reasons there are distinct levels of helper information. (A higher level always includes all properties of the previous level):
        cHelperNeighbours: explicit hydrogen atoms are moved to the end of the atom table and bonds leading to them are moved to the end of the bond table. This way algorithms can skip hydrogen atoms easily. For every atom directly connected atoms and bonds (with and without hydrogens) are determined. The number of pi electrons is counted.
        cHelperRings: Aromatic and non-aromatic rings are detected. Atom and bond ring properties are set and a ring collection provides a total set of small rings (7 or less atoms). Atoms being in allylic/benzylic or stabilized (neighbor of a carbonyl or similar group) position are flagged as such.
        cHelperParities: Atom (tetrahedral or axial) and bond (E/Z or atrop) parities are calculated from the stereo configurations.
        cHelperCIP: Cahn-Ingold-Prelog stereo information for atoms and bonds.

        cHelperParities and cHelperCIP require a StereoMolecule!!!
        Parameters:
        required - one of cHelperNeighbours,cHelperRings,cHelperParities,cHelperCIP
      • getHandleHydrogenMap

        public int[] getHandleHydrogenMap()
        If ensureHelperArrays() (and with it handleHydrogens()) was not called yet on a fresh molecule and if the molecule contains simple hydrogen atoms within non-hydrogens atoms, then this function returns a map from current atom indexes to those new atom indexes that would result from a call to handleHydrogens.
        Returns:
      • getHandleHydrogenAtomMap

        public int[] getHandleHydrogenAtomMap​(boolean[] isSimpleHydrogen)
        If ensureHelperArrays() (and with it handleHydrogens()) was not called yet on a fresh molecule and if the molecule contains simple hydrogen atoms within non-hydrogens atoms, then this function returns a map from current atom indexes to those new atom indexes that would result from a call to handleHydrogens.
        Returns:
      • getHandleHydrogenBondMap

        public int[] getHandleHydrogenBondMap()
        If ensureHelperArrays() (and with it handleHydrogens()) was not called yet on a fresh molecule and if the molecule contains simple hydrogen atoms within non-hydrogens atoms, then this function returns a map from current bond indexes to those new bond indexes that would result from a call to handleHydrogens.
        Returns:
      • isSimpleHydrogen

        public boolean isSimpleHydrogen​(int atom)
        Uncharged hydrogen atoms with no isotop information nor with an attached custom label are considered simple and can usually be suppressed, effectively converting them from an explicit to an implicit hydrogen atom.
        Note: This method returns true for uncharged, natural abundance hydrogens without custom labels even if they have a non-standard bonding situation (everything being different from having one single bonded non-simple-hydrogen neighbour, e.g. unbonded hydrogen, H2, a metal ligand bond to another atom, two single bonds, etc.) If unusual bonding needs to be considered, check for that independently from this method.
        Parameters:
        atom -
        Returns:
      • removeExplicitHydrogens

        public void removeExplicitHydrogens()
        Removes all plain explicit hydrogens atoms from the molecule, converting them effectively to implicit ones. Assuming that this molecule has 2D-coordinates, then this method perceives stereo configurations from up/down-bonds to explicit hydrogens before deleting them and turns another bond into a stereo bond to indicate the proper configuration. If the removal of a hydrogen atom would change an atom's implicit valence, the atom's abnormal valence is set accordingly.
      • removeExplicitHydrogens

        public void removeExplicitHydrogens​(boolean is3D)
        Removes all plain explicit hydrogens atoms from the molecule, converting them effectively to implicit ones. If the molecules has 2D-coordinates (is3D==false), then this method perceives stereo configurations from up/down-bonds to explicit hydrogens before deleting them and turns another bond into a stereo bond to indicate the proper configuration. If the removal of a hydrogen atom would change an atom's implicit valence, the atom's abnormal valence is set accordingly.
        Parameters:
        is3D - pass true, if atom coordinates are three dimensional