.. oe:namespace:: OEChem

.. meta::
   :keywords: OE2DRingDictionary, 2DRingDictionary


.. _OEChem_OE2DRingDictionary:

.. oe:class:: OE2DRingDictionary

   .. oe:api::

      class OE2DRingDictionary

   This class represents :ref:`OE2DRingDictionary <OEChem_OE2DRingDictionary>` that
   stores ring system layouts *i.e.* templates that can be plugged
   into the 2D coordinate generation system.

   .. seealso::

      * :ref:`chapter_2D_coordinates` chapter
      * :ref:`OE2DRingDictionaryCreatorOptions <OEChem_OE2DRingDictionaryCreatorOptions>` class
      * :oe:func:`OEChem::OEGenerate2DCoordinates` function
      * :oe:func:`OEChem::OEWrite2DRingDictionary` function

      The following **OEChem TK** examples illustrate how to create and utilize
      user-defined ring layouts:

      .. oe:language:: c++

         * Example program :ref:`createringdict.cpp<section_example_oechem_createringdict>`
         * Example program :ref:`appendringdict.cpp<section_example_oechem_appendringdict>`
         * Example program :ref:`generate2D.cpp<section_example_oechem_generate2D>`

      .. oe:language:: python

         * Example program :ref:`createringdict.py<section_example_oechem_createringdict>`
         * Example program :ref:`appendringdict.py<section_example_oechem_appendringdict>`
         * Example program :ref:`generate2D.py<section_example_oechem_generate2D>`

      .. oe:language:: java

         * Example program :ref:`CreateRingDict.java<section_example_oechem_createringdict>`
         * Example program :ref:`AppendRingDict.java<section_example_oechem_appendringdict>`
         * Example program :ref:`Generate2D.java<section_example_oechem_generate2D>`

      .. oe:language:: csharp

         * Example program :ref:`CreateRingDict.cs<section_example_oechem_createringdict>`
         * Example program :ref:`AppendRingDict.cs<section_example_oechem_appendringdict>`
         * Example program :ref:`Generate2D.cs<section_example_oechem_generate2D>`

      The following **OEDepict TK** example shows how to generate a multi-page PDF
      report of user-defined ring layouts:

      .. oe:language:: c++

         * Example program :ref:`ringdict2pdf.cpp<section_examples_summary_ringdict2pdf>`

      .. oe:language:: python

         * Example program :ref:`ringdict2pdf.py<section_examples_summary_ringdict2pdf>`

       .. oe:language:: java

         * Example program :ref:`RingDict2PDF.java<section_examples_summary_ringdict2pdf>`

       .. oe:language:: java

         * Example program :ref:`RingDict2PDF.cs<section_examples_summary_ringdict2pdf>`

   .. oe:method:: Constructors

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

         .. oe:api::

            OE2DRingDictionary()

      .. oe:language:: python

         .. oe:api:: python

            OE2DRingDictionary() -> OE2DRingDictionary

      Default constructor that creates an empty ring template dictionary
      with default parameters.

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

         .. oe:api::

            OE2DRingDictionary(const OE2DRingDictionaryCreatorOptions& opts)

      .. oe:language:: python

         .. oe:api:: python

            OE2DRingDictionary(opts: OE2DRingDictionaryCreatorOptions) -> OE2DRingDictionary

      Constructs an empty ring dictionary with the given parameters.

      .. seealso::

         * :ref:`OE2DRingDictionaryCreatorOptions <OEChem_OE2DRingDictionaryCreatorOptions>` class

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

         .. oe:api::

            OE2DRingDictionary(oemolistream& ims)
            OE2DRingDictionary(const std::string& filename)

      .. oe:language:: python

         .. oe:api:: python

            OE2DRingDictionary(filename: str) -> OE2DRingDictionary
            OE2DRingDictionary(ims: oemolistream) -> OE2DRingDictionary

      Initializes a ring dictionary from a binary file written by the
      :oe:func:`OEChem::OEWrite2DRingDictionary` function.


   .. oe:method:: operator=
      :language: c++

      .. oe:api::

         OE2DRingDictionary & operator=(const OE2DRingDictionary & rhs)

      Assignment operator.



   .. ################################################################
      # AddRings
      ################################################################

   .. oe:method:: AddRings

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

         .. oe:api::

            unsigned int AddRings(const OEMolBase& mol)

      .. oe:language:: python

         .. oe:api:: python

            AddRings(mol: Union[OEGraphMol,OEMol,OEQMol]) -> int

      Returns the number of ring systems extracted from the given
      molecule and adds them to the dictionary.

      **mol**
         The molecule **with 2D** coordinates.

      By default, the rings are extracted and added to the dictionary by the
      following rules:

      * A ring system will be added to the dictionary even if a corresponding
        layout already exists in the built-in ring dictionary *i.e.* user-defined
        layout will have higher priority.
      * If a ring system already exists in the given dictionary then the new
        ring template will be ignored *i.e* first-come first-register.
      * If a ring system has specified cis/trans bond stereo configuration then
        two layouts could be added to the ring dictionary: one with the cis/trans
        bond stereo configuration and one pure carbon skeleton framework without
        any bond stereo configuration.

      The rules above can be altered when the ring dictionary is constructed
      via the :ref:`OE2DRingDictionaryCreatorOptions <OEChem_OE2DRingDictionaryCreatorOptions>` class.


   .. ################################################################
      # NumRings
      ################################################################

   .. oe:method:: NumRings

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

         .. oe:api::

            unsigned int NumRings() const

      .. oe:language:: python

         .. oe:api:: python

            NumRings() -> int

      Returns the number of rings stored in the dictionary.
