SmilesMatcher
Date: 2019-10-22

org.jmol.smiles

## Class SmilesMatcher

- java.lang.Object
- - org.jmol.smiles.SmilesMatcher

- All Implemented Interfaces:
    SmilesMatcherInterface

      public class SmilesMatcher
      extends java.lang.Object
      implements SmilesMatcherInterface

  Originating author: Nicholas Vervelle A class to handle a variety of SMILES/SMARTS-related functions, including: -- determining if two SMILES strings are equivalent -- determining the molecular formula of a SMILES or SMARTS string -- searching for specific runs of atoms in a 3D model -- searching for specific runs of atoms in a SMILES description -- generating valid (though not canonical) SMILES and bioSMILES strings -- getting atom-atom correlation maps to be used with biomolecular alignment methods

  The original SMILES description can been found at the SMILES Home Page. Specification for this implementation can be found in package.html.

       public methods:

       int areEqual  -- checks a SMILES string against a reference (-1 for error; 0 for no finds; >0 for number of finds)

       BitSet[] find  -- finds one or more occurances of a SMILES or SMARTS string within a SMILES string

       int[][] getCorrelationMaps  -- returns correlated arrays of atoms

       String getLastError  -- returns any error that was last encountered.

       String getMolecularFormula   -- returns the MF of a SMILES or SMARTS string

       String getRelationship -- returns isomeric relationship

       String getSmiles  -- returns a standard SMILES string or a
                        Jmol BIOSMILES string with comment header.

       BitSet getSubstructureSet  -- returns a single BitSet with all found atoms included

         in Jmol script:

         string2.find("SMILES", string1)
         string2.find("SMARTS", string1)

         e.g.

           print "CCCC".find("SMILES", "C[C]")

         select search("smartsString")

         All bioSMARTS strings begin with ~ (tilde).

  Author:
    Bob Hanson

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `private static int` | `MODE_ARRAY`
    `private static int` | `MODE_ATROP`
    `private static int` | `MODE_BITSET`
    `private static int` | `MODE_MAP`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `SmilesMatcher()`

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `int` | `areEqual(java.lang.String smiles1, java.lang.String smiles2)`
    `boolean` | `areEqualTest(java.lang.String smiles, SmilesSearch search)` for JUnit test, mainly
    `java.lang.String` | `cleanSmiles(java.lang.String smiles)`
    `int[][]` | `find(java.lang.String pattern, java.lang.String target, int flags)` Searches for all matches of a pattern within a SMILES string.
    `private java.lang.Object` | `findPriv(java.lang.String pattern, SmilesSearch search, int flags, int mode)`
    `Node[]` | `getAtoms(java.lang.String target)`
    `java.lang.String` | `getAtropisomerKeys(java.lang.String pattern, Node[] atoms, int ac, javajs.util.BS bsSelected, javajs.util.BS bsAromatic, int flags)` called by SmilesParser to get nn in ^nn- base on match to actual structure
    `int[][]` | `getCorrelationMaps(java.lang.String pattern, Node[] atoms, int atomCount, javajs.util.BS bsSelected, int flags)` Rather than returning bitsets, this method returns the sets of matching atoms in array form so that a direct atom-atom correlation can be made.
    `java.lang.String` | `getLastException()`
    `int[][]` | `getMapForJME(java.lang.String jme, Atom[] at, javajs.util.BS bsAtoms)`
    `void` | `getMMFF94AtomTypes(java.lang.String[] smarts, Node[] atoms, int ac, javajs.util.BS bsSelected, javajs.util.Lst<javajs.util.BS> ret, javajs.util.Lst<javajs.util.BS>[] vRings)` called by ForceFieldMMFF.setAtomTypes only
    `java.lang.String` | `getMolecularFormula(java.lang.String pattern, boolean isSmarts)`
    `java.lang.String` | `getRelationship(java.lang.String smiles1, java.lang.String smiles2)`
    `java.lang.String` | `getSmiles(Node[] atoms, int ac, javajs.util.BS bsSelected, java.lang.String bioComment, int flags)` internal to Jmol -- called by org.jmol.Viewer.getSmiles
    `javajs.util.BS` | `getSubstructureSet(java.lang.String pattern, Node[] atoms, int ac, javajs.util.BS bsSelected, int flags)` Returns a bitset matching the pattern within a set of Jmol atoms.
    `javajs.util.BS[]` | `getSubstructureSetArray(java.lang.String pattern, Node[] atoms, int ac, javajs.util.BS bsSelected, javajs.util.BS bsAromatic, int flags)` Returns a vector of bitsets indicating which atoms match the pattern.
    `private java.lang.Object` | `matchPriv(java.lang.String pattern, Node[] atoms, int ac, javajs.util.BS bsSelected, javajs.util.BS bsAromatic, boolean doTestAromatic, int flags, int mode)`
    `java.lang.String` | `polyhedronToSmiles(Node center, int[][] faces, int atomCount, javajs.util.P3[] points, int flags, java.lang.String details)` Generate a topological SMILES string from a set of faces
    `java.lang.String` | `reverseChirality(java.lang.String smiles)` Note, this may be incompatible with [$(select(..))] THIS IS NOT DEPENDABLE.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### MODE_BITSET

          private static final int MODE_BITSET

      See Also:
        Constant Field Values

    - #### MODE_ARRAY

          private static final int MODE_ARRAY

      See Also:
        Constant Field Values

    - #### MODE_MAP

          private static final int MODE_MAP

      See Also:
        Constant Field Values

    - #### MODE_ATROP

          private static final int MODE_ATROP

      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### SmilesMatcher

          public SmilesMatcher()

  - ### Method Detail

    - #### getLastException

          public java.lang.String getLastException()

      Specified by:
        `getLastException` in interface `SmilesMatcherInterface`

    - #### getMolecularFormula

          public java.lang.String getMolecularFormula(java.lang.String pattern,
                                                      boolean isSmarts)
                                               throws java.lang.Exception

      Specified by:
        `getMolecularFormula` in interface `SmilesMatcherInterface`
      Throws:
        `java.lang.Exception`

    - #### getSmiles

          public java.lang.String getSmiles(Node[] atoms,
                                            int ac,
                                            javajs.util.BS bsSelected,
                                            java.lang.String bioComment,
                                            int flags)
                                     throws java.lang.Exception

      internal to Jmol -- called by org.jmol.Viewer.getSmiles
      Specified by:
        `getSmiles` in interface `SmilesMatcherInterface`
      Throws:
        `java.lang.Exception`

    - #### areEqual

          public int areEqual(java.lang.String smiles1,
                              java.lang.String smiles2)
                       throws java.lang.Exception

      Specified by:
        `areEqual` in interface `SmilesMatcherInterface`
      Throws:
        `java.lang.Exception`

    - #### areEqualTest

          public boolean areEqualTest(java.lang.String smiles,
                                      SmilesSearch search)
                               throws java.lang.Exception

      for JUnit test, mainly
      Parameters:
        `smiles` -
        `search` -
      Returns:
        true only if the SMILES strings match and there are no errors
      Throws:
        `java.lang.Exception`

    - #### find

          public int[][] find(java.lang.String pattern,
                              java.lang.String target,
                              int flags)
                       throws java.lang.Exception

      Searches for all matches of a pattern within a SMILES string. If SMILES (not isSmarts), requires that all atoms be part of the match.
      Specified by:
        `find` in interface `SmilesMatcherInterface`
      Parameters:
        `pattern` - SMILES or SMARTS pattern.
        `target` -
        `flags` -
      Returns:
        array of correlations of occurances of pattern within smiles
      Throws:
        `java.lang.Exception`

    - #### getAtoms

          public Node[] getAtoms(java.lang.String target)
                          throws java.lang.Exception

      Specified by:
        `getAtoms` in interface `SmilesMatcherInterface`
      Throws:
        `java.lang.Exception`

    - #### getRelationship

          public java.lang.String getRelationship(java.lang.String smiles1,
                                                  java.lang.String smiles2)
                                           throws java.lang.Exception

      Specified by:
        `getRelationship` in interface `SmilesMatcherInterface`
      Throws:
        `java.lang.Exception`

    - #### reverseChirality

          public java.lang.String reverseChirality(java.lang.String smiles)

      Note, this may be incompatible with [$(select(..))] THIS IS NOT DEPENDABLE. USE /invertStereo/ INSTEAD
      Specified by:
        `reverseChirality` in interface `SmilesMatcherInterface`

    - #### getSubstructureSet

          public javajs.util.BS getSubstructureSet(java.lang.String pattern,
                                                   Node[] atoms,
                                                   int ac,
                                                   javajs.util.BS bsSelected,
                                                   int flags)
                                            throws java.lang.Exception

      Returns a bitset matching the pattern within a set of Jmol atoms.
      Specified by:
        `getSubstructureSet` in interface `SmilesMatcherInterface`
      Parameters:
        `pattern` - SMILES or SMARTS pattern.
        `atoms` -
        `ac` -
        `bsSelected` -
      Returns:
        BitSet indicating which atoms match the pattern.
      Throws:
        `java.lang.Exception`

    - #### getMMFF94AtomTypes

          public void getMMFF94AtomTypes(java.lang.String[] smarts,
                                         Node[] atoms,
                                         int ac,
                                         javajs.util.BS bsSelected,
                                         javajs.util.Lst<javajs.util.BS> ret,
                                         javajs.util.Lst<javajs.util.BS>[] vRings)
                                  throws java.lang.Exception

      called by ForceFieldMMFF.setAtomTypes only
      Specified by:
        `getMMFF94AtomTypes` in interface `SmilesMatcherInterface`
      Throws:
        `java.lang.Exception`

    - #### getSubstructureSetArray

          public javajs.util.BS[] getSubstructureSetArray(java.lang.String pattern,
                                                          Node[] atoms,
                                                          int ac,
                                                          javajs.util.BS bsSelected,
                                                          javajs.util.BS bsAromatic,
                                                          int flags)
                                                   throws java.lang.Exception

      Returns a vector of bitsets indicating which atoms match the pattern.
      Specified by:
        `getSubstructureSetArray` in interface `SmilesMatcherInterface`
      Parameters:
        `pattern` - SMILES or SMARTS pattern.
        `atoms` -
        `ac` -
        `bsSelected` -
        `bsAromatic` -
      Returns:
        BitSet Array indicating which atoms match the pattern.
      Throws:
        `java.lang.Exception`

    - #### getAtropisomerKeys

          public java.lang.String getAtropisomerKeys(java.lang.String pattern,
                                                     Node[] atoms,
                                                     int ac,
                                                     javajs.util.BS bsSelected,
                                                     javajs.util.BS bsAromatic,
                                                     int flags)
                                              throws java.lang.Exception

      called by SmilesParser to get nn in ^nn- base on match to actual structure
      Parameters:
        `pattern` -
        `atoms` -
        `ac` -
        `bsSelected` -
        `bsAromatic` -
        `flags` -
      Returns:
        string of nn,nn,nn,nn
      Throws:
        `java.lang.Exception`

    - #### polyhedronToSmiles

          public java.lang.String polyhedronToSmiles(Node center,
                                                     int[][] faces,
                                                     int atomCount,
                                                     javajs.util.P3[] points,
                                                     int flags,
                                                     java.lang.String details)
                                              throws java.lang.Exception

      Generate a topological SMILES string from a set of faces
      Specified by:
        `polyhedronToSmiles` in interface `SmilesMatcherInterface`
      Parameters:
        `faces` -
        `atomCount` -
      Returns:
        topological SMILES string
      Throws:
        `java.lang.Exception`

    - #### getCorrelationMaps

          public int[][] getCorrelationMaps(java.lang.String pattern,
                                            Node[] atoms,
                                            int atomCount,
                                            javajs.util.BS bsSelected,
                                            int flags)
                                     throws java.lang.Exception

      Rather than returning bitsets, this method returns the sets of matching atoms in array form so that a direct atom-atom correlation can be made.
      Specified by:
        `getCorrelationMaps` in interface `SmilesMatcherInterface`
      Parameters:
        `pattern` - SMILES or SMARTS pattern.
        `atoms` -
        `bsSelected` -
      Returns:
        a set of atom correlations
      Throws:
        `java.lang.Exception`

    - #### findPriv

          private java.lang.Object findPriv(java.lang.String pattern,
                                            SmilesSearch search,
                                            int flags,
                                            int mode)
                                     throws java.lang.Exception

      Throws:
        `java.lang.Exception`

    - #### matchPriv

          private java.lang.Object matchPriv(java.lang.String pattern,
                                             Node[] atoms,
                                             int ac,
                                             javajs.util.BS bsSelected,
                                             javajs.util.BS bsAromatic,
                                             boolean doTestAromatic,
                                             int flags,
                                             int mode)
                                      throws java.lang.Exception

      Throws:
        `java.lang.Exception`

    - #### cleanSmiles

          public java.lang.String cleanSmiles(java.lang.String smiles)

      Specified by:
        `cleanSmiles` in interface `SmilesMatcherInterface`

    - #### getMapForJME

          public int[][] getMapForJME(java.lang.String jme,
                                      Atom[] at,
                                      javajs.util.BS bsAtoms)

      Specified by:
        `getMapForJME` in interface `SmilesMatcherInterface`