..  include:: ../substitutions

Molecule Builder Functions
**************************

The functions detailed in this section provide the ability to create new
molecules from basic inputs and to modify existing ones.

.. oe:function:: AtomAddHydrogens


   .. oe:api::


      void AtomAddHydrogens(const OEPropDB::OEKey &k, bool polaronly=false)

   Adds explicit hydrogens to the specified atom. If *polaronly* is set to True,
   this will only add polar hydrogens to the specified atom.

.. oe:function:: AtomAddHydrogensScoped


   .. oe:api::


      void AtomAddHydrogensScoped(bool polaronly=false, 
                                  unsigned int scope = SelectedScope)

   Scoped version of :oe:func:`AtomAddHydrogens`.

.. oe:function:: AtomAtomicNumDefaultGet


   .. oe:api::


      unsigned int AtomAtomicNumDefaultGet()

   Returns the default value of the atomic number to be used when setting the
   atomic number of an atom via a mouse action.

.. oe:function:: AtomAtomicNumDefaultSet


   .. oe:api::


      void AtomAtomicNumDefaultSet(unsigned int)

   Sets the default value of the atomic number to be used when setting the 
   atomic number of an atom via a mouse action.

.. oe:function:: AtomAtomicNumGet


   .. oe:api::


      unsigned int AtomAtomicNumGet(const OEPropDB::OEKey &k)

   Returns the atomic number of the specified atom.

.. oe:function:: AtomAtomicNumSet


   .. oe:api::


      void AtomAtomicNumSet(const OEPropDB::OEKey &k, unsigned int an)

   Sets the atomic number of the specific atom.

.. oe:function:: AtomAtomicNumSetScoped


   .. oe:api::


      void AtomAtomicNumSetScoped(unsigned int an, 
                                  unsigned int scope = SelectedScope)

   Scoped version of :oe:func:`AtomAtomicNumSet<AtomAtomicNumSet>`.

.. oe:function:: AtomAttach


   .. oe:api::


      void AtomAttach(const OEPropDB::OEKey &k, const std::string &oeb)
      void AtomAttach(const OEPropDB::OEKey &k1, const OEPropDB::OEKey &k2)
      void AtomAttach(const OEPropDB::OEKey &k, const std::string &smiles, int attach)

   Attaches the specified molecule fragment to the specified atom. There are 
   three different implementations of this function which allow for different 
   specifications of the fragment. The atom being attached to, is always the 
   first parameter. The attachment is performed by the creation of a single bond.
  
   The first implementation takes a hexadecimal encoding of a molecule specified
   in OEB format. This implementation is primarily intended for internal use.
  
   The second implementation takes an OEKey parameter specifying an atom on an 
   already loaded fragment to which the attachment will occur.

   The third implementation takes a SMILES string representing the fragment to
   be attached as well as an index specifying which atom in that fragment will be
   the attachment point.

.. oe:function:: AtomDelete


   .. oe:api::


      void AtomDelete(const OEPropDB::OEKey &k)

   Deletes the specified atom as well as any attached hydrogens.

.. oe:function:: AtomDeleteHydrogens


   .. oe:api::


      void AtomDeleteHydrogens(const OEPropDB::OEKey &k)

   Deletes all of the hydrogens attached to the specified atom.

.. oe:function:: AtomDeleteHydrogensScoped


   .. oe:api::


      void AtomDeleteHydrogensScoped(bool nonpolar=false, 
                                     unsigned int scope = SelectedScope)

   Scoped version of 
   :oe:func:`AtomDeleteHydrogens`.

.. oe:function:: AtomDeleteScoped


   .. oe:api::


      void AtomDeleteScoped(unsigned int scope = SelectedScope)

   Scoped version of 
   :oe:func:`AtomDelete`.

.. oe:function:: AtomFormalChargeDefaultGet


   .. oe:api::


      int AtomFormalChargeDefaultGet()

   Returns the default value of the formal to be used when setting the
   formal of an atom via a mouse action.

.. oe:function:: AtomFormalChargeDefaultSet


   .. oe:api::


      void AtomFormalChargeDefaultSet(int)

   Sets the default value of the formal to be used when setting the
   formal of an atom via a mouse action.

.. oe:function:: AtomFormalChargeGet


   .. oe:api::


      int AtomFormalChargeGet(const OEPropDB::OEKey &k)

   Returns the formal charge for the specified atom.

.. oe:function:: AtomFormalChargeModify


   .. oe:api::


      void AtomFormalChargeModify(const OEPropDB::OEKey &k, int delta)

   Modifies the formal charge on the specified atom by the specified delta 
   value. The delta value can be either positive or negative.

.. oe:function:: AtomFormalChargeModifyScoped


   .. oe:api::


      void AtomFormalChargeModifyScoped(int delta, 
                                        unsigned int scope = SelectedScope)

   Scoped version of 
   :oe:func:`AtomFormalChargeModify`.

.. oe:function:: AtomFormalChargeSet


   .. oe:api::


      void AtomFormalChargeSet(const OEPropDB::OEKey &k, int chg)

   Sets the formal charge on the specified atom.

.. oe:function:: AtomFormalChargeSetScoped


   .. oe:api::


      void AtomFormalChargeSetScoped(int chg, 
                                     unsigned int scope = SelectedScope)

   Scoped version of 
   :oe:func:`AtomFormalChargeSet`.

.. oe:function:: AtomFuse


   .. oe:api::


      void AtomFuse(const OEPropDB::OEKey &k, const std::string &oeb)
      void AtomFuse(const OEPropDB::OEKey &k1, const OEPropDB::OEKey &k2)
      void AtomFuse(const OEPropDB::OEKey &k, const std::string &smiles, int attach)

   Fuses the specified molecule fragment to the specified atom. There are 
   three different implementations of this function which allow for different 
   specifications of the fragment. The atom being fused to is always the 
   first parameter.
  
   The first implementation takes a hexadecimal encoding of a molecule specified
   in OEB format. This implementation is primarily intended for internal use.
  
   The second implementation takes an OEKey parameter specifying an atom on an 
   already loaded fragment where the fusion will occur.

   The third implementation takes a SMILES string representing the fragment to
   be fused as well as an index specifying which atom in that fragment will be
   the site of the fusion.

.. oe:function:: AtomHybridizationGet


   .. oe:api::


      unsigned int AtomHybridizationGet(const OEPropDB::OEKey &k)

   Returns the hybridization state of the specified atom.

.. oe:function:: AtomHybridizationSet


   .. oe:api::


      void AtomHybridizationSet(const OEPropDB::OEKey &k, unsigned int hyb)

   Sets the hybridization state of the specified atom.  

.. oe:function:: AtomHybridizationSetScoped


   .. oe:api::


      void AtomHybridizationSetScoped(unsigned int hyb, 
                                      unsigned int scope = SelectedScope)


   Scoped version of
   :oe:func:`AtomHybridizationSet`.

.. oe:function:: AtomIsotopeGet


   .. oe:api::


      unsigned int AtomIsotopeGet(const OEPropDB::OEKey &k)

   Returns the isotope of the specified atom.

.. oe:function:: AtomIsotopeSet


   .. oe:api::


      void AtomIsotopeSet(const OEPropDB::OEKey &k, unsigned int iso)

   Sets the isotope for the specified atom.

.. oe:function:: AtomIsotopeSetScoped


   .. oe:api::


      void AtomIsotopeSetScoped(unsigned int iso, 
                                unsigned int scope = SelectedScope)

   Scoped version of
   :oe:func:`AtomIsotopeSet`.

.. oe:function:: AtomSprout


   .. oe:api::


      void AtomSprout(const OEPropDB::OEKey &k, unsigned int elem=6, 
                      unsigned int order=1)

   Sprouts a new atom off of the specified atom. The atomic number of the new 
   atom is specified by *elem* and the order of the bond to the new atom is 
   specified by the *order* parameter.

.. oe:function:: AtomSproutScoped


   .. oe:api::


      void AtomSproutScoped(unsigned int elem=6, unsigned int order=1, 
                            unsigned int scope = SelectedScope)

   Scoped version of 
   :oe:func:`AtomSprout`.

.. oe:function:: AtomStereoDefaultGet


   .. oe:api::


      std::string AtomStereoDefaultGet()
      
   Returns the default value for the stereochemistry setting to be used when
   setting the stereochemistry via a mouse action. Allowed values include:
  
   * "R"
   * "S"
   * "Invert"  

.. oe:function:: AtomStereoDefaultSet


   .. oe:api::


      void AtomStereoDefaultSet(const std::string &s)

   Sets the default value for the stereochemistry setting to be used when
   setting the stereochemistry via a mouse action. Allowed values include:
  
   * "R"
   * "S"
   * "Invert"  

.. oe:function:: AtomStereoSet


   .. oe:api::


      void AtomStereoSet(const OEPropDB::OEKey &k, const std::string &s)

   Sets the CIP stereochemistry of the specified atom. Allowed values are "R"
   and "S".
  
.. oe:function:: AtomStereoSetScoped


   .. oe:api::


      void AtomStereoSetScoped(const std::string &s, 
                               unsigned int scope = SelectedScope)

   Scoped version of
   :oe:func:`AtomStereoSet`.

.. oe:function:: AtomStereoToggle


   .. oe:api::


      void AtomStereoToggle(const OEPropDB::OEKey &k)

   Toggles the stereochemistry of the specified atom.

.. oe:function:: AtomStereoToggleScoped


   .. oe:api::


      void AtomStereoToggleScoped(unsigned int scope = SelectedScope)

   Scoped version of:
   :oe:func:`AtomStereoToggle`.

.. oe:function:: BondAngleGet


   .. oe:api::


      double BondAngleGet(const OEPropDB::OEKey &k1, const OEPropDB::OEKey &k2)
      double BondAngleGet(const OEPropDB::OEKey &k1, const OEPropDB::OEKey &k2, 
                          const OEPropDB::OEKey &k3)

   Returns the angle between the two specified bonds or the three specified 
   atoms.

.. oe:function:: BondAngleModify


   .. oe:api::


      void BondAngleModify(const OEPropDB::OEKey &k1, const OEPropDB::OEKey &k2, 
                           double angle, unsigned int rmode)
      void BondAngleModify(const OEPropDB::OEKey &k1, const OEPropDB::OEKey &k2, 
                           const OEPropDB::OEKey &k3, double ang, unsigned int rmode)

   Modifies the angle between the two specified bonds or the three specified 
   atoms. The amount by which the angle is adjusted is specified by the *angle*
   parameter. The portion of the molecule which is actually moved in this 
   process is specified by the *rmode* parameter:
  
   * 0 - the smaller portion of the molecule will be moved
   * 1 - the larger portion of the molecule will be moved

.. oe:function:: BondAngleSet


   .. oe:api::


      void BondAngleSet(const OEPropDB::OEKey &k1, const OEPropDB::OEKey &k2, 
                        double angle, unsigned int rmode)
      void BondAngleSet(const OEPropDB::OEKey &k1, const OEPropDB::OEKey &k2, 
                        const OEPropDB::OEKey &k3, double ang, unsigned int rmode)

   Sets the angle between the two specified bonds or the three specified 
   atoms. The desired angle is specified by the *angle* parameter. The portion 
   of the molecule which is actually moved in this process is specified by the 
   *rmode* parameter:
  
   * 0 - the smaller portion of the molecule will be moved
   * 1 - the larger portion of the molecule will be moved

.. oe:function:: BondCreate


   .. oe:api::


      void BondCreate(const OEPropDB::OEKey &k1, const OEPropDB::OEKey &k2, 
                      unsigned int order=1, double length=0.0)

   Creates a new bond between the two specified atoms with an order and length
   specified by the two eponymous parameters.

..  _vida_bonddelete:

.. oe:function:: BondDelete


   .. oe:api::


      void BondDelete(const OEPropDB::OEKey &k)

   Deletes the specified bond.

.. oe:function:: BondDeleteScoped


   .. oe:api::


      void BondDeleteScoped(unsigned int scope = SelectedScope)

   Scoped version of :ref:`BondDelete <vida_bonddelete>`.

.. oe:function:: BondFuse


   .. oe:api::


      void BondFuse(const OEPropDB::OEKey &b, const std::string &oeb)
      void BondFuse(const OEPropDB::OEKey &b1, const OEPropDB::OEKey &b2)
      void BondFuse(const OEPropDB::OEKey &b, const OEPropDB::OEKey &e, 
                    const std::string &oeb)
      void BondFuse(const OEPropDB::OEKey &b, const std::string &smiles, int battach, 
                    int eattach)
      void BondFuse(const OEPropDB::OEKey &b1, const OEPropDB::OEKey &e1, 
                    const OEPropDB::OEKey &b2, const OEPropDB::OEKey &e2)
      void BondFuse(const OEPropDB::OEKey &beg, const OEPropDB::OEKey &end, 
                    const std::string &smiles, int battach, int eattach)

   Fuses two bonds together. There are multiple implementations of this function
   which allow for different mechanisms of specifying the source bond as well as
   the target bond (and associated fragment). The source bond can be specified 
   using a distinct bond key or by specifying the keys of the beginning and end
   atoms of that bond. The target bond can also be specified using a distinct
   bond key or by two keys representing the beginning and end atoms of the bond.
   However, the target bond can also be set as part of a specified fragment.
  
   One implementation allows for specification of a hexadecimal encoded OEB
   string representing the molecule fragment and selected target bond. This
   method is primarily intended for internal use.
  
   The other mechanism allows for specification of the fragment as a SMILES
   string associated with an index for the beginning and end atoms defining
   the bond.

.. oe:function:: BondLengthGet


   .. oe:api::


      double BondLengthGet(const OEPropDB::OEKey &k)
      double BondLengthGet(const OEPropDB::OEKey &k1, const OEPropDB::OEKey &k2)

   Returns the length of the specified bond. The bond can be specified using 
   either a bond key or two atom keys corresponding to the endpoints of the 
   bond.

.. oe:function:: BondLengthModify


   .. oe:api::


      void BondLengthModify(const OEPropDB::OEKey &k, double len, unsigned int rmode)
      void BondLengthModify(const OEPropDB::OEKey &k1, const OEPropDB::OEKey &k2, 
                            double length, unsigned int rmode)

   Modifies the length of the specified bond by the amount specified in the 
   *len* parameter. The bond can be specified using either a bond key or two
   atom keys corresponding to the endpoints of the bond. The portion of the
   molecule which is actually moved is determined by the *rmode* parameter. 
   Available values include:
  
   * 0 - the smaller portion of the molecule is moved
   * 1 - the larger portion of the molecule is moved

.. oe:function:: BondLengthSet


   .. oe:api::


      void BondLengthSet(const OEPropDB::OEKey &k, double len, unsigned int rmode)
      void BondLengthSet(const OEPropDB::OEKey &k1, const OEPropDB::OEKey &k2, 
                         double length, unsigned int rmode)


   Sets the length of the specified bond to the value specified in the 
   *len* parameter. The bond can be specified using either a bond key or two
   atom keys corresponding to the endpoints of the bond. The portion of the
   molecule which is actually moved is determined by the *rmode* parameter. 
   Available values include:
  
   * 0 - the smaller portion of the molecule is moved
   * 1 - the larger portion of the molecule is moved

.. oe:function:: BondLengthSetScoped


   .. oe:api::


      void BondLengthSetScoped(double length, 
                               unsigned int rmode=OEForge::RotateMode::Smaller, 
                               unsigned int scope = SelectedScope)

   Scoped version of
   :oe:func:`BondLengthSet`.

.. oe:function:: BondOrderDefaultGet


   .. oe:api::


      unsigned int BondOrderDefaultGet()
      
   Returns the default value of the bond order used when setting the order of a
   bond through a mouse action.

.. oe:function:: BondOrderDefaultSet


   .. oe:api::


      void BondOrderDefaultSet(unsigned int)

   Sets the default value of the bond order used when setting the order of a
   bond through a mouse action.

.. oe:function:: BondOrderGet


   .. oe:api::


      unsigned int BondOrderGet(const OEPropDB::OEKey &k)
      unsigned int BondOrderGet(const OEPropDB::OEKey &k1, const OEPropDB::OEKey &k2)

   Returns the order of the specified bond. The bond can be specified as a
   distinct bond key or two keys corresponding to the endpoint atoms.

.. oe:function:: BondOrderSet


   .. oe:api::


      void BondOrderSet(const OEPropDB::OEKey &k, unsigned int order)
      void BondOrderSet(const OEPropDB::OEKey &k1, const OEPropDB::OEKey &k2, 
                        unsigned int order)

   Sets the order of the specified bond. The bond can be specified as a
   distinct bond key or two keys corresponding to the endpoint atoms.

.. oe:function:: BondOrderSetScoped


   .. oe:api::


      void BondOrderSetScoped(unsigned int order, unsigned int scope)

   Scoped version of
   :oe:func:`BondOrderSet`.

.. oe:function:: BondStereoDefaultGet


   .. oe:api::


      std::string BondStereoDefaultGet()
 
   Returns the default value for bond stereochemistry setting to be used when
   setting the stereochemistry via a mouse action. Allowed values include:
  
   * "E"
   * "Z"
   * "Invert"  

.. oe:function:: BondStereoDefaultSet


   .. oe:api::


      void BondStereoDefaultSet(const std::string &)

   Sets the default value for bond stereochemistry setting to be used when
   setting the stereochemistry via a mouse action. Allowed values include:
  
   * "E"
   * "Z"
   * "Invert"  

.. oe:function:: BondStereoSet


   .. oe:api::


      void BondStereoSet(const OEPropDB::OEKey &k, const std::string &s)
      void BondStereoSet(const OEPropDB::OEKey &k1, const OEPropDB::OEKey &k2, 
                         const std::string &s)

   Sets the CIP stereochemistry for the specified bond. The bond can be 
   specified as a distinct bond key or by two atom keys corresponding to the
   endpoint atoms. Allowed values for stereochemistry include:
  
   * "E"
   * "Z"

.. oe:function:: BondStereoSetScoped


   .. oe:api::


      void BondStereoSetScoped(const std::string &s, 
                               unsigned int scope = SelectedScope)

   Scoped version of
   :oe:func:`BondStereoSet`.

.. oe:function:: BondStereoToggle


   .. oe:api::


      void BondStereoToggle(const OEPropDB::OEKey &k)
      void BondStereoToggle(const OEPropDB::OEKey &k1, const OEPropDB::OEKey &k2)

   Toggles the stereochemistry for the specified bond. The bond can be specified
   as a distinct bond key or by two atom keys corresponding to the endpoint 
   atoms.

.. oe:function:: BondStereoToggleScoped


   .. oe:api::


      void BondStereoToggleScoped(unsigned int scope = SelectedScope)

   Scoped version of :oe:func:`BondStereoToggle`.

.. oe:function:: BondTorsionGet


   .. oe:api::


      double BondTorsionGet(const OEPropDB::OEKey &k1, const OEPropDB::OEKey &k2, 
                            const OEPropDB::OEKey &k3)
      double BondTorsionGet(const OEPropDB::OEKey &k1, const OEPropDB::OEKey &k2, 
                            const OEPropDB::OEKey &k3, const OEPropDB::OEKey &k4)

   Returns the torsion (dihedral) angle specified by either three bonds or four
   atoms. The order of specification is important in the determination of the
   angle.

.. oe:function:: BondTorsionModify


   .. oe:api::


      void BondTorsionModify(const OEPropDB::OEKey &k1, const OEPropDB::OEKey &k2, 
                             const OEPropDB::OEKey &k3, double t, unsigned int rmode)
      void BondTorsionModify(const OEPropDB::OEKey &k1, const OEPropDB::OEKey &k2, 
                             const OEPropDB::OEKey &k3, const OEPropDB::OEKey &k4, 
                             double torsion, unsigned int rmode)

   Modifies the torsion (dihedral) angle specified by either three bonds or four
   atoms. The amount the angle is modified by is specified by the *torsion* 
   parameter. The portion of the molecule which is moved by this function is
   specified by the *rmode* parameter. Available values include:
  
   * 0 - the smaller portion of the molecule moves
   * 1 - the larger portion of the molecule moves

.. oe:function:: BondTorsionSet


   .. oe:api::


      void BondTorsionSet(const OEPropDB::OEKey &k1, const OEPropDB::OEKey &k2, 
                          const OEPropDB::OEKey &k3, double t, unsigned int rmode)
      void BondTorsionSet(const OEPropDB::OEKey &k1, const OEPropDB::OEKey &k2, 
                          const OEPropDB::OEKey &k3, const OEPropDB::OEKey &k4, 
                          double torsion, unsigned int rmode)

   Sets the torsion (dihedral) angle specified by either three bonds or four
   atoms. The desired angle is specified by the *torsion* parameter. The portion 
   of the molecule which is moved by this function is specified by the *rmode* 
   parameter. Available values include:
  
   * 0 - the smaller portion of the molecule moves
   * 1 - the larger portion of the molecule moves

.. oe:function:: BuilderActiveGet


   .. oe:api::


      bool BuilderActiveGet()

   Returns whether or not VIDA is in molecule editing mode.

.. oe:function:: BuilderActiveSet


   .. oe:api::


      void BuilderActiveSet(bool)

   Sets whether or not VIDA is in molecule editing mode.

.. oe:function:: BuilderAlternateConfModeGet


   .. oe:api::


      bool BuilderAlternateConfModeGet()

   Returns whether or not VIDA is in ring alternate conformation
   exploration mode.

.. oe:function:: BuilderAlternateConfModeSet


   .. oe:api::


      void BuilderAlternateConfModeSet(bool)

   Sets whether or not VIDA is in ring alternate conformation exploration
   mode.

.. oe:function:: BuilderAlternateConfSet


   .. oe:api::


      void BuilderAlternateConfSet(unsigned int)

   Applies the specified alternate ring conformation to the molecule currently
   being edited. This is intended for internal use only.

.. oe:function:: BuilderCancel


   .. oe:api::


      void BuilderCancel()

   Cancels all modifications made to the molecule currently being edited and
   exits editing mode.

.. oe:function:: BuilderEdit


   .. oe:api::


      void BuilderEdit(const OEPropDB::OEKey &, bool force3D)

   Puts VIDA into editing mode for the specified molecule.  If the molecule
   is a 2D molecule, setting the *force3D* parameter to True will ensure that 3D
   coordinates will be generated, even if the user cancels out of editing mode.

.. oe:function:: BuilderFinish


   .. oe:api::


      void BuilderFinish()

   Commits all modifications made to the molecule currently being edited and
   exits editing mode.

.. oe:function:: BuilderFragmentGet


   .. oe:api::


      std::string BuilderFragmentGet()

   Returns a hexadecimal encoded OEB string representation of the current
   fragment being used in the builder component.

.. oe:function:: BuilderFragmentSet


   .. oe:api::


      void BuilderFragmentSet(const std::string &oeb)
      void BuilderFragmentSet(const std::string &smiles, int)

   Sets the default fragment to be used in mouse actions in the builder. The
   first implementation takes a hexadecimal encoded OEB string representation
   of the molecule fragment (this is primarily intended for internal use). The
   second implementation takes a SMILES string with an additional index 
   parameter which specifies the index of the atom to be used as the attachment
   point.

.. oe:function:: BuilderMinimize


   .. oe:api::


      void BuilderMinimize()

   Minimizes the molecule currently being edited using the MMFF forcefield.

.. oe:function:: BuilderMinimizeScoped


   .. oe:api::


      void BuilderMinimizeScoped(unsigned int scope = SelectedScope)

   Minimizes a portion of the molecule currently being edited as determined by 
   the atoms in the specified scope. Valid values for the scope parameter are:
  
   * MarkedScope
   * SelectedScope
   * ScratchScope

.. oe:function:: BuilderPropertiesGet


   .. oe:api::


      std::vector<string> BuilderPropertiesGet()

   Returns a list of the properties displayed in the Property table of the
   Builder window.

.. oe:function:: BuilderPropertyAdd


   .. oe:api::


      void BuilderPropertyAdd(const std::string &name, const std::string &command, unsigned int flags = CalculateForSmallMols)

   Adds a user-defined property calculator to the Properties table of the 
   Builder window.  The *name* parameter is the name of the property to be 
   calculated.  The *command* parameter is a string containing a Python command
   to be executed to calculate the property.  The return value of the command
   is displayed in the property table.  The *flags* parameter specifies what
   types of molecules the property will be calculated for, and whether a change
   to a molecule's coordinates requires the property to be recalculated.  Valid
   values for this parameter are:

   * UpdateOnCoordChange
   * CalculateForSmallMols
   * CalculateForProteins

   These values can be OR'ed together to be used in combinations.  The property
   is always recalculated when the chemical graph of the active molecule 
   changes.  

   To add one of |product's| default properties (*e.g.*, 'LogP') to the 
   property table, use its name and leave the *command* string empty.

.. oe:function:: BuilderPropertyRemove


   .. oe:api::


      void BuilderPropertyRemove(const std::string &propertyToRemove)

   Removes a property from the Property table of the Builder window.

.. oe:function:: BuilderPropertySetValue


   .. oe:api::


      void BuilderPropertySetValue(const std::string &propertyName, const std::string &value)

   Directly sets a value in the Property table of the Builder window.  The 
   value will be overwritten when the property is updated.

.. oe:function:: BuilderTorsionActivate


   .. oe:api::


      void BuilderTorsionActivate(const OEPropDB::OEKey &key)

   Activates an existing torsion monitor, specified by key, so that it can be
   rotated interactively while in Editing mode.  Activating a torsion will 
   temporarily display two torsion measurements, one for each end of the bond.
   When one of these measurements is selected, the corresponding end of the 
   molecule will be moved when the mouse wheel or up/down arrows are used.  If 
   this command is used outside of Editing mode, the double measurements will be
   displayed but will not be activated.

.. oe:function:: BuilderTorsionsDeactivate


   .. oe:api::


      void BuilderTorsionsDeactivate()

   Returns all active torsion monitors to their inactive state.
  
.. oe:function:: BuilderUseMMFF94sSet


   .. oe:api::


      void BuilderUseMMFF94sSet(bool useMMFF94s)

   Causes the builder geometry optimizations to use the MMFF94s force field,
   which provides more nearly planar geometries for delocalized trigonal
   nitrogens than the MMFF94 force field.  Calling this function with
   *useMMFF94s* = False will cause the builder to revert to using MMFF94.

.. oe:function:: BuilderUseMMFF94sGet


   .. oe:api::


      bool BuilderUseMMFF94sGet()

   Returns True if the builder is currently set to use the MMFF94s force field,
   or False if the builder is using the MMFF94 force field.

.. oe:function:: MoleculeAddExplicitHydrogens


   .. oe:api::


      void MoleculeAddExplicitHydrogens(const OEPropDB::OEKey &k, 
                                        bool polarOnly=false)

   Adds explicit hydrogens to the specified molecule. If the *polarOnly* 
   parameter is specified, only polar hydrogens will be added.

.. oe:function:: MoleculeAddHydrogens


   .. oe:api::


      void MoleculeAddHydrogens(const OEPropDB::OEKey &k, bool polarOnly=false)

   This function adds hydrogens to the molecule associated with the specified
   key. If the *polarOnly* parameter is set, only polar hydrogens will be added.

.. oe:function:: MoleculeAddHydrogensScoped


   .. oe:api::


      void MoleculeAddHydrogensScoped(bool polarOnly=false, 
                                      unsigned int scope = BestScope)

   This function adds hydrogens to the molecules int the specified scope. If the 
   *polarOnly* parameter is set, only polar hydrogens will be added.

.. oe:function:: MoleculeDeleteHydrogens


   .. oe:api::


      void MoleculeDeleteHydrogens(const OEPropDB::OEKey &k, bool nonpolar=false)

   Deletes hydrogens off of the specified molecule. If the *nonpolar* parameter
   is True, it will only delete non-polar hydrogens, leaving the molecule with
   only polar hydrogens still attached.

.. oe:function:: MoleculeGenerateCoords


   .. oe:api::


      void MoleculeGenerateCoords(const OEPropDB::OEKey &k, 
                                  unsigned int maxconfs=1, 
                                  bool strict=false)

   Generates new coordinates for the specified molecule. The maximum number of 
   conformations can be specified using the *maxconfs* parameter. Strict stereo 
   can be turn on using the *strict* parameter.

.. oe:function:: MoleculeGenerateCoordsFixed


   .. oe:api::


      void MoleculeGenerateCoordsFixed(const OEPropDB::OEKey &k, 
                                       const std::vector<OEPropDB::OEKey> &fixed, 
                                       bool match=true, unsigned int maxconfs=1, 
                                       bool strict=false)

   Generates new coordinates for the specified molecule while holding fixed
   either the specified atoms (if the *match* parameter is True) or all the
   unspecified atoms (if the *match* parameter is False). The maximum number of
   conformations can be specified use the *maxconfs* parameter. Strict stereo 
   can be turn on using the *strict* parameter.

.. oe:function:: MoleculeGenerateCoordsFixedScoped


   .. oe:api::


      void MoleculeGenerateCoordsFixedScoped(const OEPropDB::OEKey &k, 
                                             bool match=true, unsigned int maxconfs=1, 
                                             unsigned int scope = SelectedScope,
                                             bool strict)

   Generates new coordinates for the specified molecule while holding fixed
   either all the atoms in the specified scope (if the *match* parameter is 
   True) or all the atoms not in specified scope (if the *match* parameter is 
   False). The maximum number of conformations can be specified use the 
   *maxconfs* parameter. Strict stereo can be turn on using the *strict* parameter.

.. oe:function:: MoleculeNew


   .. oe:api::


      OEPropDB::OEKey MoleculeNew(const std::string &text, unsigned int listid=0)

   Creates a new molecule from the specified text representation. Allowed text 
   representations include SMILES as well as IUPAC and common names. A FASTA
   sequence can also be specified if preceded by an angle bracket character 
   ('>'). 
   
   Assuming that the molecule can be created from the specified text, it will 
   be added to the specified list (*listid*). If the list ID is zero, a new 
   list will be created.
   
   Returns the key corresponding to this molecule.

.. oe:function:: MoleculeRotate


   .. oe:api::


      void MoleculeRotate(const OEPropDB::OEKey &key,
                          int oldx, oldy, int newx, int newy)

   Rotates a molecule's coordinates corresponding to a mouse move in the 3D
   display window.

.. oe:function:: SketcherInputSet


   .. oe:api::


      void SketcherInputSet(const std::string &smilesString)
      void SketcherInputSet(OEMol &molecule)

   Sets the molecule in the Sketcher from the provided SMILES string or 
   molecule.  If an existing 3D molecule is already in build mode, this 
   method will throw an exception.

.. oe:function:: SketcherLookupFunctionSet


   .. oe:api::


      void SketcherLookupFunctionSet(const std::string &functionString)

   Sets a Python function to be called for compound name lookups.  The lookup
   function should accept a string, convert that to either SMILES or a
   molecule, and call :oe:func:`SketcherInputSet` to put the resulting molecule
   into the Sketcher.  The ``functionString`` argument should include only
   the name of the lookup function, without parentheses or arguments, *e.g.*, 
   'MyLookupFunction'.
   
