.. include:: ../../toolkit-substitutions

.. oe:namespace:: OEDataFlow

.. attention::

   |TWOLANGUAGE|

.. meta::
   :keywords: OEMolRecord OERecord datarecord

.. _OEDataFlow_OEMolRecord:

.. oe:class:: OEMolRecord

   .. seealso::

      * :ref:`chapter_oemolrecord` chapter

   .. oe:language:: c++

      .. attention::

        |TWOLANGUAGE|

      .. oe:api::

         class OEMolRecord

      The :ref:`OEMolRecord <OEDataFlow_OEMolRecord>` class is a subclass of
      :ref:`OERecord <OEDataFlow_OERecord>`, with additional convenience
      methods for handling molecules. All public methods from
      :ref:`OERecord <OEDataFlow_OERecord>` are inherited. This class has
      a "primary" molecule field, to which several convenience methods apply.

      .. ################################################################
         # Constructors
         ################################################################

      .. oe:method:: Constructors

         .. oe:api::

            OEMolRecord()

         The default constructor initializes the record object to an empty
         record with no fields or values.

         .. oe:api::

            OEMolRecord(const OERecord& rhs)

         Copy constructor. OEMolRecords can be constructed from OERecords,
         and vice versa, without any loss of data.


      .. ################################################################
         #
         ################################################################

      .. oe:method:: GetPrimaryMolField

         .. oe:api::

            OEField<OEChem::OEMol> GetPrimaryMolField(const std::string defName = "Molecule",
                                                      OEFieldMeta meta = OEFieldMeta()) const

         Retrieves the primary molecule field from the record. If no primary
         molecule field exists, this will return a field of type
         Types::Chem::Molecule with the name "Molecule".

         defName
           The name to be used for the molecule field if a primary molecule
           field doesn't already exist ont he record.

         meta
           An optional OEFieldMeta object specifying metadata for the field.

      .. seealso::

         * :ref:`OEField <OEDataFlow_OEField>`



      .. ################################################################
         #
         ################################################################

      .. oe:method:: GetMol

         .. oe:api::

            OEChem::OEMol GetMol(OEFieldBase field = OEFieldBase()) const

         Retrieves a molecule from the record. If no field is specified, the
         record's primary molecule is returned. If no primary molecule exists,
         an default-constructed (empty) OEMol is returned.

         field
           The field to retrieve the molecule from. If this is omitted, the
           record's primary molecule will be returned.

      .. seealso::

         * :ref:`OEFieldBase <OEDataFlow_OEFieldBase>`

      .. ################################################################
         #
         ################################################################

      .. oe:method:: HasMol

         .. oe:api::

            bool HasMol(OEFieldBase field = OEFieldBase()) const

         Returns true if the record has a molecule in the specified field,
         or a primary molecule if no field is supplied.

         field
           The field to check for the presence of a molecule. If this is
           omitted, the record's primary molecule will be used.

      .. seealso::

         * :ref:`OEFieldBase <OEDataFlow_OEFieldBase>`

      .. ################################################################
         #
         ################################################################

      .. _OEDataFlow_SetMol_CPP:

      .. oe:method:: SetMol

         .. oe:api::

            bool SetMol(const OEChem::OEMol& mol,
                        OEFieldBase field = OEFieldBase(),
                        OEFieldMeta meta = OEFieldMeta())

         Sets a molecule on the record using the specified field. If no field
         is supplied, the primary molecule is set.

         mol
           The molecule to be copied to the record.

         field
           The field to store the molecule on. If this is omitted, the molecule
           will be stored as the record's primary molecule.

         meta
           Optional metadata to store on the field.

      .. seealso::

         * :ref:`OEFieldBase <OEDataFlow_OEFieldBase>` class
         * :ref:`OEFieldMeta <OEDataFlow_OEFieldMeta>` class


      .. ################################################################
         #
         ################################################################

      .. oe:method:: GetMolPointer

         .. oe:api::

            OEChem::OEMol* GetMolPointer(OEFieldBase field = OEFieldBase())

         Returns a pointer to the molecule from the specified field on the
         record, or to the primary molecule if no field is supplied. If no
         such molecule exists on the record, a null pointer is returned.

         field
           The field from which the molecule pointer is obtained. If this
           argument is omitted, a pointer to the primary molecule is returned.

      .. seealso::

         * :oe:meth:`OEDataFlow::OEMolRecord::HasMol` method
         * :ref:`OEFieldBase <OEDataFlow_OEFieldBase>` class

      .. note::

         This method will return a pointer to the actual molecule on the record,
         so any modifications to this molecule will affect the record contents.
         Accessing this pointer after the record has been destroyed will have
         undefined results.

      .. ################################################################
         #
         ################################################################

      .. oe:method:: SetMolReference

         .. oe:api::

            bool SetMolReference(OEChem::OEMol& mol,
                                 OEFieldBase field = OEFieldBase(),
                                 OEFieldMeta meta = OEFieldMeta())

         This method puts a pointer to the passed OEMol onto the record, in
         the specified field. If no field is provided, the record's primary
         molecule is set. While the
         :ref:`SetMol <OEDataFlow_SetMol_CPP>` method places
         a *copy* of the passed molecule onto the record, this method avoids
         creating a copy, and may in some cases improve performance.

         mol
           The molecule to be placed on the record.

         field
           The field to store the molecule in. If this is omitted the molecule
           will be stored in the record's primary molecule field.

         meta
           Optional metadata to be stored on the field.

      .. seealso::

         * :oe:meth:`OEDataFlow::OEMolRecord::SetMol` method
         * :oe:meth:`OEDataFlow::OEMolRecord::GetMolPointer` method
         * :ref:`OEFieldBase <OEDataFlow_OEFieldBase>` class
         * :ref:`OEFieldMeta <OEDataFlow_OEFieldMeta>` class


      .. ################################################################
         #
         ################################################################

      .. oe:method:: GetConfRecord

         .. oe:api::

            OERecord GetConfRecord(const OEChem::OEConfBase* conf) const

         Returns a record for the provided conformer. OEMolRecord provides a
         mechanism for storing a record of data for each conformer. If the
         passed conformer doesn't already have a record associated with it,
         this will return an empty OERecord.

         conf
           The conformer the record will be associated with.


      .. ################################################################
         #
         ################################################################

      .. oe:method:: SetConfRecord

         .. oe:api::

            void SetConfRecord(const OEChem::OEConfBase* conf,
                               OERecord& childRecord)

         This method associates data on a record with a conformer. The
         conformer's parent molecule must be stored in a field on the parent
         record *after* this method is called, or stored using the
         :oe:meth:`OEDataFlow::OEMolRecord::SetMolReference` method.
         Otherwise, the conformer data will be lost during serialization.

         childRecord
           A record containing data for the conformer.

      .. seealso::

         * :oe:meth:`OEDataFlow::OEMolRecord::GetConfRecord`
         * :oe:meth:`OEDataFlow::OEMolRecord::SetMolReference`

   .. oe:language:: python

      .. oe:api::

         class OEMolRecord

      The :ref:`OEMolRecord <OEDataFlow_OEMolRecord>` class is a subclass of
      :ref:`OERecord <OEDataFlow_OERecord>`, with additional convenience
      methods for handling molecules. All public methods from
      :ref:`OERecord <OEDataFlow_OERecord>` are inherited. This class has
      a "primary" molecule field, to which several convenience methods apply.


      .. ################################################################
         # Constructors
         ################################################################

      .. oe:method:: Constructors

         .. oe:api::

            OEMolRecord()

         The default constructor initializes the record object to an empty
         record with no fields or values.

         .. oe:api::

            OEMolRecord(const OERecord &rhs)

         Copy constructor. OEMolRecords can be constructed from OERecords,
         and vice versa, without any loss of data.


      .. ################################################################
         #
         ################################################################

      .. oe:method:: get_primary_mol_field

         .. oe:api::

            get_primary_mol_field(def_name: str = "Molecule",
                                  meta: OEFieldMeta = None) -> object

         Retrieves the primary molecule field from the record. If no primary
         molecule field exists, this will return a field of type
         Types.Chem.Molecule with the name "Molecule".

         def_name
           The name to be used for the molecule field if a primary molecule
           field doesn't already exist ont he record.

         meta
           An optional OEFieldMeta object specifying metadata for the field.

      .. seealso::

         * :ref:`OEField <OEDataFlow_OEField>`



      .. ################################################################
         #
         ################################################################

      .. oe:method::  get_mol

         .. oe:api::

            get_mol(field: OEFieldBase) -> OEMol

         Retrieves a molecule from the record. If no field is specified, the
         record's primary molecule is returned. If no primary molecule exists,
         None is returned.

         field
           The field to retrieve the molecule from. If this is omitted, the
           record's primary molecule will be returned.

      .. seealso::

         * :ref:`OEFieldBase <OEDataFlow_OEFieldBase>`

      .. ################################################################
         #
         ################################################################

      .. oe:method:: has_mol

         .. oe:api::

            has_mol(field: OEFieldBase = None) -> bool

         Returns True if the record has a molecule in the specified field,
         or a primary molecule if no field is supplied.

         field
           The field to check for the presence of a molecule. If this is
           omitted, the record's primary molecule will be used.

      .. seealso::

         * :ref:`OEFieldBase <OEDataFlow_OEFieldBase>`

      .. ################################################################
         #
         ################################################################

      .. _OEDataFlow_SetMol_Python:

      .. oe:method:: set_mol

         .. oe:api::

            set_mol(mol: OEMol, field: OEFieldBase = None,
                    meta: OEFieldMeta = None) -> bool

         Sets a molecule on the record using the specified field. If no field
         is supplied, the primary molecule is set.

         mol
           The molecule to be copied to the record.

         field
           The field to store the molecule on. If this is omitted, the molecule
           will be stored as the record's primary molecule.

         meta
           Optional metadata to store on the field.

      .. seealso::

         * :ref:`OEFieldBase <OEDataFlow_OEFieldBase>` class
         * :ref:`OEFieldMeta <OEDataFlow_OEFieldMeta>` class


      .. ################################################################
         #
         ################################################################

      .. _get_mol_reference:

      .. oe:method:: get_mol_reference

         .. oe:api::

            get_mol_reference(field: OEFieldBase = None) -> OEMol

         Returns a reference to the molecule from the specified field on the
         record, or to the primary molecule if no field is supplied. If no
         such molecule exists on the record, None is returned.

         field
           The field from which the molecule pointer is obtained. If this
           argument is omitted, a pointer to the primary molecule is returned.

      .. seealso::

         * :oe:meth:`OEDataFlow::OEMolRecord::has_mol` method
         * :ref:`OEFieldBase <OEDataFlow_OEFieldBase>` class

      .. note::

         This method will return a reference to the actual molecule on the
         record, so any modifications to this molecule will affect the record
         contents.

      .. ################################################################
         #
         ################################################################

      .. oe:method:: set_mol_reference

         .. oe:api::

            set_mol_reference(mol: OEMol, field: OEFieldBase = None,
                              meta: OEFieldMeta = None) -> bool

         This method puts a reference to the passed OEMol onto the record, in
         the specified field. If no field is provided, the record's primary
         molecule is set. While the :ref:`SetMol <OEDataFlow_SetMol_Python>` method places
         a *copy* of the passed molecule onto the record, this method avoids
         creating a copy, and may in some cases improve performance.

         mol
           The molecule to be placed on the record.

         field
           The field to store the molecule in. If this is omitted the molecule
           will be stored in the record's primary molecule field.

         meta
           Optional metadata to be stored on the field.

      .. seealso::

         * :oe:meth:`OEDataFlow::OEMolRecord::set_mol` method
         * :oe:meth:`OEDataFlow::OEMolRecord::get_mol_reference` method
         * :ref:`OEFieldBase <OEDataFlow_OEFieldBase>` class
         * :ref:`OEFieldMeta <OEDataFlow_OEFieldMeta>` class


      .. ################################################################
         #
         ################################################################

      .. oe:method:: get_conf_record

         .. oe:api::

            get_conf_record(conf: OEConfBase) -> OERecord

         Returns a record for the provided conformer. OEMolRecord provides a
         mechanism for storing a record of data for each conformer. If the
         passed conformer doesn't already have a record associated with it,
         this will return an empty OERecord.

         conf
           The conformer the record will be associated with.


      .. ################################################################
         #
         ################################################################

      .. oe:method:: set_conf_record

         .. oe:api::

            set_conf_record(conf: OEConfBase, child_record: OERecord) -> null

         This method associates data on a record with a conformer. The
         conformer's parent molecule must be stored in a field on the parent
         record *after* this method is called, or stored using the
         :oe:meth:`OEDataFlow::OEMolRecord::set_mol_reference` method.
         Otherwise, the conformer data will be lost during serialization.

         child_record
           A record containing data for the conformer.

      .. seealso::

         * :oe:meth:`OEDataFlow::OEMolRecord::get_conf_record`
         * :oe:meth:`OEDataFlow::OEMolRecord::set_mol_reference`

