.. _builder:

..  include:: substitutions

*********************
Molecule Manipulation
*********************

|product| has the ability to both create and modify existing molecules. The
focus is primarily on small molecules, but it is not limited to small 
molecules. Molecules can only be modified in a specific *Editing* mode, more
details of which are available in the following sections.

.. _creating_molecules:

Creating Molecules
==================

A new molecule can be created from scratch in |product| by clicking on the
button in the main toolbar with the icon of a molecule overlaid with a plus
sign (see :ref:`Table: Builder Icons<figure_builder_icons>`). Clicking this 
button will open |product's| sketcher window.

.. _figure_sketcher_vida:

.. include:: 2dsketcher.rst

.. _editing_molecules:

Editing Molecules
=================

Molecules can only be changed in |product| when in *Editing* mode. Only a 
single molecule can be in *Editing* mode at a time. To put a molecule into
*Editing* mode, select the "Edit" option from the right-click popup menu or
click on the button in the main toolbar with the icon of a molecule overlaid 
with a pencil (see :ref:`Table: Builder Icons<figure_builder_icons>`).

.. _figure_builder_icons:

.. list-table:: **Builder Icons**
  :widths: 15 50
  :header-rows: 1

  * - Button
    - Description
  * - .. image:: images/builder/icon_open_2dsketcher.png
        :align: center
    - **Sketch new molecule:** Opens the 2D Sketcher to allow creation of a 
      new molecule.
  * - .. image:: images/builder/icon_open_builder.png
        :align: center
    - **Edit current molecule:** Places the current active molecule into the
      3D Builder and 2D Sketcher.
  * - .. image:: images/builder/icon_accept_builder.png
        :align: center
    - **Save as new molecule:** Saves the edited molecule as a new entry while
      remaining in Editing mode.
  * - .. image:: images/builder/icon_cancel_builder.png
        :align: center
    - **Accept edits:** Leaves Editing mode and keeps the changes made to the
      edited molecule.
  * - .. image:: images/builder/icon_builder_saveas.png
        :align: center
    - **Cancel edits:** Leaves Editing mode and cancels any unsaved edits.


On entering *Editing* mode, the "Open 3D Builder" icon will be replaced by one of 
a molecule with a green "+" sign.  This icon will close the Builder and keep any changes
made to the molecule during editing.  An additional button also appears in the toolbar
with the icon of a molecule overlaid with a red "X". Clicking on this button will
cancel out all of the changes made to the molecule and will restore the 
molecule back to its original state. 

When |product| enters *Editing* mode, a number of builder tools appear in
the 3D window, and the Sketcher window opens, allowing editing of a molecule
in either 2D or 3D.  The 2D and 3D editing functions are roughly equivalent,
and are synchronized, so that selecting a tool in the 3D window will select 
the corresponding tool (where possible) in the 2D sketcher and vice versa.  
The various building tools are discussed in detail in :ref:`creating_molecules`.

.. _figure_edit_molecule:

.. figure:: images/builder/3D_builder.png
   :scale:  75
   :align:  center
   
   **Molecule Editing**

.. _builder_icon_table:

.. list-table::
  :widths: 15 50
  :header-rows: 1
  
  * - Icon
    - Description
  * - .. image:: images/builder/icon_select.png
    - **Select:**  This is the default selection mode.  With the icon highlighted 
      click on the atoms or bonds to be selected or Shift-click or Ctrl-click to 
      incrementally select multiple atoms and/or bonds.  The selected atoms and bonds 
      will be highlighted in orange.  Double click to select whole functional groups
      or molecules.  Select a group of atoms and bonds within a rectangle using 
      right-click and drag.
  * - .. image:: images/builder/icon_information.png
    - **Information:**  Clicking on an atom or bond provides information such as
      atom type, 3D Cartesian coordinates, bond type and bond length.
  * - .. image:: images/builder/icon_center.png
    - **Center:**  Select the center tool and then click on an atom to center the view
      on that atom
  * - .. image:: images/builder/icon_distance_angle_torsion.png
    - **Monitors:**  Place monitors for distance (2 atoms), angle (3 atoms) or torsion
      (4 atoms).  Click sequentially on the atoms to be included in the monitor.  Before
      the last atom is clicked hovering over an atom will display a temporary monitor.  
      Clicking on the atom makes the monitor persist.
  * - .. image:: images/builder/icon_add_label.png
    - **Add Labels:**  With the tool selected click on an atom or bond to add label text.
  * - .. image:: images/builder/icon_erase.png
    - **Delete:**  Delete atoms and/or bonds by selecting the eraser tool and clicking on the 
      atom or bond to be deleted.  To delete groups of atoms or bonds first select them 
      with the Selection tool and then either use the *Delete* option in the right-click
      menu or use the *Delete* keyboard key.
  * - .. image:: images/builder/icon_add_fragment.png
    - **Rings:**  
      Click on the small arrow to open a dropdown menu and select from some commonly 
      used rings, such as benzene, cyclopropane and cyclohexane. The selected  
      ring can be added to the growing molecule multiple times.  There is also an 
      option to define a Custom functional group.  This opens the 2D sketcher into 
      which the functional group can be sketched or a SMILES string can be input.    

      This icon shows an image of the currently active ring template.  The default is benzene.
  * - .. image:: images/builder/icon_atom.png
    - **Element:**  
      Click on the small arrow to open a dropdown menu and select from some commonly 
      used elements.  Clicking on an atom in the main 3D window will cause 
      that atom to be changed to the selected atom type.  In addition to the 
      commonly used atoms there is an "X" dummy atom type.  Clicking the "..." option in 
      the list opens a full periodic table of the elements from which a wider range
      of elements can be selected.

      This icon shows an image of the currently active atom type.  The default is 
      "C".
  * - .. image:: images/builder/icon_bond.png
    - **Bond order:**  
      Clicking on a bond in the main 3D Builder window will cycle through
      the available bond orders for that bond.
  * - .. image:: images/builder/icon_charge.png
    - **Charge:**  Click on the small arrow to open a dropdown and select the formal 
      charge for an atom.  Options available are -2, -1, 0, +1, +2.  Other formal
      charges not in this range can be set with the "..." option.  With the 
      charge icon active (highlighted white) clicking on any atom in the main 
      sketcher window will modify the atom to have the currently selected charge.

      This icon displays an image of the currently active charge.  
      The default is "-2".
  * - .. image:: images/builder/icon_stereochemistry.png
    - **Stereochemistry:**  Click on the small arrow to open a dropdown and select 
      atom and bond CIP stereochemistry options.  Available options are R and S 
      for chiral atoms and E or Z for chiral bonds.  There is also an option to 
      invert the current stereochemistry.

      This icon displays an image of the currently active option.  
      The default is "Invert".

When a molecule enters *Editing* mode, |product| adds explicit hydrogens to the
molecule to properly fill out the valences. In addition, labels are added to 
both atoms and bonds to indicate stereochemistry and formal charge.

A molecule can be edited by either setting the mouse mode using the buttons on 
the right or by clicking on one or more atoms/bonds and then selecting the 
desired operation from the context sensitive right-click menu. The menu provides the 
following choices.  Some options are available only when atoms are selected and
others only when bonds are selected.

.. _builder_menu_table:

.. list-table:: **Builder Right-Click Menu**
  :widths: 10 50
  :header-rows: 0

  * - **Center**  
    - Centers the highlighted atom(s) in the display.
  * - **Set Element**  
    - Atoms only. Select the desired atom type from a Periodic Table.  This atom type 
      will be applied to all the selected atoms.
  * - **Set Formal Charge**  
    - Atoms only. Select the formal charge for all the selected atoms.
  * - **Set Torsion**  
    - Specify a torsion angle for a 4-atom set.
  * - **Set Bond Order** 
    - Bonds only. Specify the desired bond order.  Applies to all the 
      highlighted bonds.
  * - **Set Bond Length** 
    - Bonds only.  Specify the desired bond length.  
      The new length is applied to all the highlighted bonds.
  * - **Modify Torsion** 
    - Bonds or 4-atom sets only.  Use the keyboard *up* and *down* arrow keys
      or the mouse scroll wheel to increase and decrease the bond torsion.
  * - **Modify Angle** 
    - 3-atom sets only. Use the keyboard *up* and *down* arrow keys to
      increase and decrease the bond angle.
  * - **Sprout Methyl** 
    - Atoms only. If the selected atom has an open valence (i.e. bond to H)
      this option will replace the H-atom with a methyl group.
  * - **Create Bond**  
    - Atoms only. Make a new bond between two selected atoms with open valences.
  * - **Attach** 
    - Atoms only.  Opens the 2D sketcher to input the fragment to be attached
      to the highlighted atom.
  * - **Fuse** 
    - Opens the 2D sketcher to input the fragment to be fused to the 
      highlighted atom or bond.
  * - **Measure Length** 
    - Bonds only.  Displays a monitor with the bond length. 
  * - **Measure Torsion** 
    - Bonds only.  Displays a monitor for the torsion around the bond(s).
  * - **Measure Angle** 
    - Atoms only. Displays a monitor with the bond length.
  * - **Minimize** 
    - Atoms only.  Minimize the highlighted portion of the molecule using
      the MMFF94 or MMFF94s force field.
  * - **Delete**  
    - Delete the highlighted atoms or bonds.  Open valences will be filled
      with H-atoms.
  * - **Cancel Editing**  
    - Exit the 3D builder without keeping any of the changes.
  * - **Finish Editing**  
    - Exit the 3D builder and accept the edits.
  * - **Create**  
    - A sub-menu provides options for creating molecular or accessible
      surfaces or electrostatic grids.
  * - **Bookmarks**  
    - A sub-menu provides options to add or organize bookmarks and define
      animation preferences.
  * - **Delete Visible Monitors**  
    - Deletes all visible monitors (angle, length, torsion)
      from the 3D display.

Independent Rotation/Translation of Molecules
---------------------------------------------

It is possible to rotate and translate a molecule in *Editing* mode independently from
all other molecules in |product|, by holding down the *Ctrl* key (*Command* key on the 
Macintosh) during rotation or translation actions.  Any selected atoms will define the 
center of rotation.  If no atoms are selected, the centroid of the molecule is used for 
the center of rotation.


.. _editing_minimization:

Minimization
------------

An entire molecule or just a subset of a molecule can be minimized using the 
MMFF94 or MMFF94s forcefield. This minimization takes place in a vacuum and does not take 
into account any context (such as a protein active site).

.. _figure_icon_minimize:

.. figure:: images/builder/icon_minimize.png
   :align:  center
   
   **Minimize Tool**

To minimize a molecule, the molecule of interest must be in *Editing* mode. 
Once *Editing* mode has been enabled for a molecule, a button with a magic wand
icon (see :ref:`Figure: Minimize<figure_icon_minimize>`) will appear on the right hand 
side of the 3D display. Clicking on this 
button will cause the entire molecule or just the selected subset of the 
molecule to be minimized. Like all other procedures in |product|, the 
minimization process can be undone.

Monitors
--------

Angle, distance, and torsion monitors can be added to individual molecules to
display as well as modify the associated properties. Monitors can be created 
using the monitor mouse mode (available from the toolbar on the left side of
the :ref:`3D display<builder_icon_table>`). Torsion monitors can also be created by first selecting a 
single bond, three adjacent bonds, or four adjacent atoms and then choosing
the *Modify Torsion* option in the right-click menu.

The value associated with a distance or angle monitor can be changed by selecting the
monitor of interest and then scrolling the mouse wheel. By default, the smaller
side of the molecule will be the one modified by these changes; however, if the
*Ctrl* key is held down while using the mouse wheel, the larger side will be
modified instead.  

In the builder, torsion monitors are added in pairs, with one monitor at each end
of the selected bond.  The monitor you select will determine which end of the bond
will rotate.  (By default the monitor on the smaller side of the molecule is
selected.)

To rotate torsions within a ring, create a torsion monitor on a ring bond, then
select one other bond in the ring as a "closure bond".  The closure bond will
stretch and deform as you adjust the torsion.  When finished with the adjustment,
you will probably want to minimize the ring structure using the *Minimize Tool* 
(see :ref:`Figure: Minimize<figure_icon_minimize>`).

The figure below illustrates adjusting a ring torsion to convert a cyclohexyl group from chair to boat conformation.  The active torsion monitor and closure bond are shown selected.

.. _figure_chair_boat:

.. figure:: images/pucker_chair_boat.png
   :scale:  100
   :align:  center

   **Ring Pucker Conversion.**  *Interconversion of a ring from chair to boat conformation can be performed by rotating a single ring torsion.*

Torsion monitors can also be used to convert between equatorial and axial 
substitutions of a ring, as shown in the following figure.  In this example,
a single torsion is rotated in two steps, using two different closure bonds.

.. _figure_equat_axial:

.. figure:: images/pucker_equat_axial.png
   :scale: 100
   :align: center

   **Equatorial to Axial Conversion.**  *An equatorial substitution on a 
   cyclohexyl ring is converted to an axial substitution by adjusting a 
   ring torsion.  In step 3 a new closure bond is selected, and the torsion
   rotated farther, until a chair conformation is obtained.*

When adjusting torsions, the default step size is 10 degrees; however, a finer
resolution of 1 degree can be achieved by simultaneously holding down the 
*Shift* key while using the mouse wheel.
