Class StereoMolecule

    • Field Detail

      • VALIDATION_ERROR_ESR_CENTER_UNKNOWN

        public static final java.lang.String VALIDATION_ERROR_ESR_CENTER_UNKNOWN
        See Also:
        Constant Field Values
      • VALIDATION_ERROR_OVER_UNDER_SPECIFIED

        public static final java.lang.String VALIDATION_ERROR_OVER_UNDER_SPECIFIED
        See Also:
        Constant Field Values
      • VALIDATION_ERROR_AMBIGUOUS_CONFIGURATION

        public static final java.lang.String VALIDATION_ERROR_AMBIGUOUS_CONFIGURATION
        See Also:
        Constant Field Values
      • VALIDATION_ERRORS_STEREO

        public static final java.lang.String[] VALIDATION_ERRORS_STEREO
    • Constructor Detail

      • StereoMolecule

        public StereoMolecule()
      • StereoMolecule

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

        public StereoMolecule​(Molecule mol)
    • Method Detail

      • createMolecule

        public StereoMolecule createMolecule​(int atoms,
                                             int bonds)
      • copyMoleculeProperties

        public void copyMoleculeProperties​(Molecule destMol)
        Copies name, isFragment, chirality. If this molecule has valid parities, but no atom coordinates, then the validity of parity & CIP flags is copied as well. When copying molecules parts only or when changing the atom order during copy, then atom parities or CIP parities may not be valid anymore and invalidateHelperArrays([affected bits]) should be called in these cases.
        Overrides:
        copyMoleculeProperties in class Molecule
        Parameters:
        destMol -
      • getFragments

        public StereoMolecule[] getFragments()
        Separates all disconnected fragments of this Molecule into individual Molecule objects. If fragment separation is only needed, if there are multiple fragments, it may be more efficient to run this functionality in two steps, e.g.:
        int[] fragmentNo = new int[mol.getAllAtoms()];
        int fragmentCount = getFragmentNumbers(fragmentNo, boolean, boolean);
        if (fragmentCount > 1) {
        StereoMolecule[] fragment = getUniqueFragmentsEstimated(int[] fragmentNo, fragmentCount);
        ...
        }
        Returns:
      • getFragments

        public StereoMolecule[] getFragments​(int[] fragmentNo,
                                             int fragmentCount)
        Separates all disconnected fragments of this Molecule into individual molecule objects. The parameters fragmentNo and fragmentCount are typically obtained from a call of getFragmentNumbers().
        Parameters:
        fragmentNo -
        fragmentCount -
        Returns:
      • ensureHelperArrays

        public void ensureHelperArrays​(int required)
        ensureHelperArrays() is the essential method when working with molecules. The Molecule class contains all primary information about a molecule, i.e. the connectivity of atoms and bonds and their properties. The ExtendedMolecule, which is derived from the Molecule add functionality to keep track of direct neighbours of atoms, rings and aromaticity. The StereoMolecule, which in turn is derived from the ExtendedMolecule, is responsible for the stereo recognition. It employs a Canonizer object to run a complete atom symmetry evaluation and to locate all stereo centers and bonds. It also checks the molecule for meso state.
        Whenever the molecule connectivity changes (e.g. through methods like addAtom(), setAtomCharge() or deleteBond()), then the state of the computed 'helper' data as neighbour aroms, ring information or stereo information gets invalid. Therefore, after constructing or changing a molecule and before accessing any of the helper data (e.g. getConnAtoms(), isAromaticAtom(), or getAtomParity()) one must ensure that the required information is in a valid state by calling ensureHelperArrays() passing the required level of information:
        - cHelperNeighbours: neighbour atoms and bonds, pi-electrons for all atoms
        - cHelperRings: cHelperNeighbours plus rings,aromaticity/allylic/stabilized for non-H-atoms
        - cHelperParities: cHelperRings plus stereo parities for non-H-atoms/bonds
        - cHelperCIP: cHelperParities plus Cahn-Ingold-Prelog assignments for non-H-atoms/bonds
        Call ensureHelperArrays(cHelperParities) only if either parities are available anyway (e.g. from idcode parsing) or if coordinates with stereo bonds are available. Call ensureHelperArrays(cHelperCIP) only if coordinates with stereo bonds are available.
        Overrides:
        ensureHelperArrays in class ExtendedMolecule
        Parameters:
        required - typically one of cHelperNeighbours,cHelperRings,cHelperParities,cHelperCIP
      • stripStereoInformation

        public void stripStereoInformation()
        Removes defined and implicit stereo information from the molecule.
        - up/down-bonds are converted to double bonds
        - stereo centers are flagged to be unknown
        - double bonds with implicit stereo configurations are converted into cross bonds
        - all atom and bond ESR assignments are removed
        - parity and CIP helper state is set to invalid, such that stereo calculation is redone, if needed.
      • getAbsoluteAtomParity

        public int getAbsoluteAtomParity​(int atom)
        This returns the absolute(!) atom parity from the canonization procedure. While the molecule's (relative) atom parity returned by getAtomParity() is based on atom indices and therefore depends on the order of atoms, the absolute atom parity is based on atom ranks and therefore independent of the molecule's atom order. Usually relative parities are used, because the atom's stereo situation can be interpreted without the need for atom rank calculation. This requires valid helper arrays level cHelperParities or higher.
        Parameters:
        atom -
        Returns:
        one of the Molecule.cAtomParityXXX constants
      • getAbsoluteBondParity

        public int getAbsoluteBondParity​(int bond)
        This returns the absolute(!) bond parity from the canonization procedure. While the molecule's (relative) bond parity returned by getBondParity() is based on atom indices and therefore depends on the order of atoms, the absolute bond parity is based on atom ranks and therefore independent of the molecule's atom order. Usually relative parities are used, because the bond's stereo situation can be interpreted without the need for atom rank calculation. This requires valid helper arrays level cHelperParities or higher.
        Parameters:
        bond -
        Returns:
        one of the Molecule.cBondParityXXX constants
      • getSymmetryRank

        public int getSymmetryRank​(int atom)
        This returns atom symmetry numbers from within the molecule canonicalization procedure. Atoms with same symmetry numbers can be considered topologically equivalent. Symmetry ranks are only available after calling ensureHelperArrays(cHelperSymmetry...). In mode cHelperSymmetrySimple stereoheterotopic atoms are considered equivalent. In mode cHelperSymmetryDiastereotopic only diastereotopic atoms are distinguished. In mode cHelperSymmetryEnantiotopic all stereoheterotopic atoms, i.e. enantiotopic and diastereotopic atoms, are distinguished.
      • getIDCode

        public java.lang.String getIDCode()
        This is a convenience method that creates the molecule's idcode without explicitly creating a Canonizer object for this purpose. The idcode is a compact String that uniquely encodes the molecule with all stereo and query features.
        WARNING: If the molecule has no atom coordinates but valid parities, e.g. after new IDCodeParser(false).parse(idcode, null), this method returns null;
        Returns:
      • getIDCoordinates

        public java.lang.String getIDCoordinates()
        This is a convenience method that creates the molecule's id-coordinates matching the idcode available with getIDCode(). It does not explicitly create a Canonizer object for this purpose.
        WARNING: If the molecule has no atom coordinates but valid parities, e.g. after new IDCodeParser(false).parse(idcode, null), this method returns null;
        Returns:
      • getCanonizer

        public Canonizer getCanonizer()
        This is a convenience method returning the StereoMolecule's Canonizer object after calling internally ensureHelperArrays(cHelperParities) and, thus, effectively running the canonicalization and validating the Canonizer itself.
        WARNING: If the molecule has no atom coordinates but valid parities, e.g. after new IDCodeParser(false).parse(idcode, null), this method returns null;
        Returns:
      • getStereoCenterCount

        public int getStereoCenterCount()
      • getESRGroupMemberCounts

        public int[][] getESRGroupMemberCounts()
      • setUnknownParitiesToExplicitlyUnknown

        public void setUnknownParitiesToExplicitlyUnknown()
        Sets all atoms with TH-parity 'unknown' to explicitly defined 'unknown'. Sets all double bonds with EZ-parity 'unknown' to cross bonds. Sets the first bond atom of all BINAP type bonds with parity 'unknown' to explicitly defined 'unknown' parity.
      • setAssignParitiesToNitrogen

        public void setAssignParitiesToNitrogen​(boolean b)
        This is a policy setting for this StereoMolecule as molecule container. If set to true then this StereoMolecule will treat tetrahedral nitrogen atoms with three or four distinguishable substituents as stereo centers and will assign parities. deleteMolecule() does not change this behavior.
        Parameters:
        b -
      • translateTHParity

        public int translateTHParity​(int atom,
                                     int[] targetAtomIndex)
        This method translates the parity of a stereo center, if its neighbour atoms are assigned new atom indexes, or are assigned to a matching fragment or molecule with different atom indexes. Since the tetrahedral stereo parity is based on atom indexes, we need to translate when atom indexes change. Assumes helper array state: cHelperParities.
        Parameters:
        atom -
        targetAtomIndex - mapping from this molecule's atom index to the target molecule's
        Returns:
        translated atom parity
      • validate

        public void validate()
                      throws java.lang.Exception
        Overrides:
        validate in class ExtendedMolecule
        Throws:
        java.lang.Exception