.. include:: ../substitutions

.. oe:namespace:: OEChem

.. meta::
   :keywords: OEShortestPath

.. oe:function:: OEShortestPath

   .. list-table:: **The overloaded versions of the OEShortestPath function**
      :widths: 100 200
      :header-rows: 1

      * - Link
        - Description

      * - :ref:`OEShortestPath(atomA, atomB)<api_OEShortestPath_OEAtomBase_OEAtomBase>`
        - find shortest path between two atoms
      * - :ref:`OEShortestPath(atomA, atomB, atompred)<api_OEShortestPath_OEAtomBase_OEAtomBase_AtomPred>`
        - find shortest path between two atoms (excluding certain atoms)
      * - :ref:`OEShortestPath(atomA, atomB, bondpred)<api_OEShortestPath_OEAtomBase_OEAtomBase_BondPred>`
        - find shortest path between two atoms (excluding certain bonds)

   .. _api_OEShortestPath_OEAtomBase_OEAtomBase:

   .. oe:language:: c++ java csharp

      .. oe:api::

         OESystem::OEIterBase<OEAtomBase>* OEShortestPath(const OEAtomBase* a,
                                                          const OEAtomBase* b)

   .. oe:language:: python

      .. oe:api:: python

         OEShortestPath(a: OEAtomBase, b: OEAtomBase) -> OEAtomIter

   Returns a shortest path between the two given atoms. If no path exists
   the :oe:func:`OEChem::OEShortestPath` function returns an empty iterator.

   **Example**

   .. oe:source:: ShortestPath.py
      :language: python
      :noindent:
      :frag:     SNIPPET-OESHORTESTPATH

   .. oe:source:: ShortestPath.cpp
      :language: c++
      :noindent:
      :frag:     SNIPPET-OESHORTESTPATH

   .. oe:source:: ShortestPath.java
      :language: java
      :noindent:
      :frag:     SNIPPET-OESHORTESTPATH

   .. oe:source:: ShortestPath.cs
      :language: cs
      :noindent:
      :frag:     SNIPPET-OESHORTESTPATH

   .. _figure_OEShortestPath:

   .. figure:: ../images/OEShortestPath.*
      :align:  center

      **Example of shortest path between atom 2 and 8**

   .. note::

      The shortest path returned by the :oe:func:`OEChem::OEShortestPath` function is
      non-unique. There are more than one valid shortest path can exist between two
      atoms. The :oe:func:`OEChem::OEShortestPath` only returns one of them.
      For example, there are three valid six atoms long shortest path exist between atom
      1 and 7 in the example above:  ``1, 2, 3, 9, 8, 7``,  ``1, 0, 5, 4, 6, 7``, and
      ``1, 2, 3, 4, 6, 7``.

   .. _api_OEShortestPath_OEAtomBase_OEAtomBase_AtomPred:

   .. oe:language:: c++ java csharp

      .. oe:api::

         OESystem::OEIterBase<OEAtomBase>* OEShortestPath(const OEAtomBase* a,
                                                          const OEAtomBase* b,
                                                          const OESystem::OEUnaryPredicate<OEAtomBase>& excludeatoms)

   .. oe:language:: python

      .. oe:api:: python

         OEShortestPath(a: OEAtomBase, b: OEAtomBase,
                        excludeAtoms: OEUnaryAtomPred) -> OEAtomIter

   Returns a shortest path between the two given atoms. The returned path will exclude
   any atom that satisfies the given atom predicate.
   If no path exists the :oe:func:`OEChem::OEShortestPath` function returns
   an empty iterator.

   **Example**

   .. oe:source:: ShortestPath.py
      :language: python
      :noindent:
      :frag:     SNIPPET-OESHORTESTPATH-EXCLUDE

   .. oe:source:: ShortestPath.cpp
      :language: c++
      :noindent:
      :frag:     SNIPPET-OESHORTESTPATH-EXCLUDE

   .. oe:source:: ShortestPath.java
      :language: java
      :noindent:
      :frag:     SNIPPET-OESHORTESTPATH-EXCLUDE

   .. oe:source:: ShortestPath.cs
      :language: cs
      :noindent:
      :frag:     SNIPPET-OESHORTESTPATH-EXCLUDE


   .. _figure_OEShortestPathAtomPredicate:

   .. figure:: ../images/OEShortestPath_AtomPredicate.*
      :align:  center

      **Example of shortest path between atom 2 and 8 without traversing any nitrogen atom**

   .. _api_OEShortestPath_OEAtomBase_OEAtomBase_BondPred:

   .. oe:language:: c++ java csharp

      .. oe:api::

         OESystem::OEIterBase<OEAtomBase>* OEShortestPath(const OEAtomBase* a,
                                                          const OEAtomBase* b,
                                                          const OESystem::OEUnaryPredicate<OEBondBase>& excludebonds)

   .. oe:language:: python

      .. oe:api:: python

         OEShortestPath(a: OEAtomBase, b: OEAtomBase,
                        excludeBonds: OEUnaryBondPred) -> OEAtomIter

   Returns a shortest path between the two given atoms. The returned path will exclude
   any bond that satisfies the given bond predicate.
   If no path exists, the :oe:func:`OEChem::OEShortestPath` function returns
   an empty iterator.

.. seealso::

   * :oe:func:`OEChem::OEGetPathLength` function

   .. oe:language:: c++

      * Example program :ref:`minpath.cpp<section_example_oechem_minpath>`

   .. oe:language:: python

      * Example program :ref:`minpath.py<section_example_oechem_minpath>`

   .. oe:language:: java

      * Example program :ref:`MinPath.java<section_example_oechem_minpath>`

   .. oe:language:: csharp

      * Example program :ref:`MinPath.cs<section_example_oechem_minpath>`
